docs: add docstrings

README.md

-# Repository for common swagger documentation and apps versions of prozorro infrastructure
\ No newline at end of file
+# Repository for common swagger documentation and apps versions of prozorro infrastructure
+
+### Auto Dock
+To generate sphinx docs
+```
+make dev-docs
+```
\ No newline at end of file

doc8.ini

+[doc8]
+max-line-length=120
\ No newline at end of file

src/prozorro_doc/conf.py

+"""
+Provides environment and configuration variables used in the service.
+
+For more information see https://gitlab.prozorro.sale/prozorro-sale/prozorro-tools/
+"""
+
 from prozorro_sale.tools.environment import Environment, booleans
 from pathlib import Path
 
@@ -8,7 +14,8 @@ DOC_ENV_VARS = {
 }
 ENV_DEFAULTS = {
     'INITIAL_CACHE_DELAY': 600,
-    'WORKING_DIR': Path()
+    'WORKING_DIR': Path('/'),
+    'SWAGGER_DOC': False,
 }
 
 ENV_VARS = Environment(spec=DOC_ENV_VARS, default=ENV_DEFAULTS)

src/prozorro_doc/constants.py

@@ -16,7 +16,7 @@ def allowed_services():
     Returns:
         dict: service name, service url
     """
-    data_path = Path(f"{ENV_VARS['WORKING_DIR']}", "/config/services.yml")
+    data_path = Path(f"{ENV_VARS['WORKING_DIR']}", "config/services.yml")
     with open(data_path) as fp:
         services = load(fp, Loader=Loader)
     data = {service: f'http://{url}' if 'http' not in url else url for service, url in services.items() if url}
@@ -24,7 +24,6 @@ def allowed_services():
 
 
 SWAGGER_FILE_PATH = pathlib.Path('/swagger_ui3/index.html')
-SWAGGER_DOC_AVAILABLE = ENV_VARS['SWAGGER_DOC']
 
 CACHED_DATA_PATH = '/cached'
 

src/prozorro_doc/main.py

@@ -9,7 +9,7 @@ from prozorro_sale.tools.api_requests import setup_async_api_requests
 from prozorro_doc.conf import DOC_ENV_VARS, ENV_VARS
 from prozorro_doc.utils import get_swagger_on_startup
 from prozorro_doc.views import ping, swagger, doc, version
-from prozorro_doc.constants import URL_MAPPING, SWAGGER_DOC_AVAILABLE
+from prozorro_doc.constants import URL_MAPPING
 from prozorro_sale.tools import logger
 from prozorro_sale.tools.middlewares import request_id_middleware
 
@@ -17,7 +17,9 @@ LOG = logger.get_custom_logger(__name__)
 
 
 async def init_swagger_cache():
-    """Create asynchronous task to create swagger documentation with time delay"""
+    """
+    Create asynchronous task to create swagger documentation with time delay
+    """
     await asyncio.sleep(ENV_VARS['INITIAL_CACHE_DELAY'])
     tasks = []
 
@@ -28,7 +30,8 @@ async def init_swagger_cache():
 
 
 async def create_schedule(app):
-    """Initialize schedule for creation of swagger documentation.
+    """
+    Initialize schedule for creation of swagger documentation.
 
     Args:
         app (aiohttp.web.Application): Application object.
@@ -42,7 +45,8 @@ async def create_schedule(app):
 
 
 async def on_shutdown(app):
-    """Executes on app shutdown.
+    """
+    Executes on app shutdown.
 
     Args:
     app (aiohttp.web.Application): Application object.
@@ -58,13 +62,13 @@ async def on_shutdown(app):
 
 
 def create_application():
-    """Initializing application.
+    """
+    Initializing application.
 
     Returns:
         aiohttp.web.Application: Application object.
 
     """
-
     app = web.Application(middlewares=[
         request_id_middleware,
     ])
@@ -79,16 +83,16 @@ def create_application():
 
 
 def setup_routes(app):
-    """List of available routes for the application.
+    """
+    List of available routes for the application.
 
     Returns:
         None.
     """
-
     app.router.add_get('/api/ping', ping)
     app.router.add_get('/api/doc/version', version)
 
-    if SWAGGER_DOC_AVAILABLE:
+    if ENV_VARS['SWAGGER_DOC']:
         app.router.add_get('/api/doc/{doc_type}/swagger.json', swagger)
         app.router.add_get('/api/doc', doc)
         app.router.add_static(prefix='/api/doc', path='/swagger_ui3')

src/prozorro_doc/utils.py

@@ -11,7 +11,8 @@ LOG = logger.get_custom_logger(__name__)
 
 
 def cached_swagger_full_path(doc_type) -> Path:
-    """Create folder for cached data and returns path.
+    """
+    Create folder for cached data and returns path.
 
     Args:
         doc_type(str): service name
@@ -25,7 +26,8 @@ def cached_swagger_full_path(doc_type) -> Path:
 
 
 def get_cached_swagger_path(doc_type) -> Path:
-    """Validate swagger cache path, returns if existed.
+    """
+    Validate swagger cache path, returns if existed.
 
     Args:
         doc_type(str): service name
@@ -40,14 +42,15 @@ def get_cached_swagger_path(doc_type) -> Path:
 
 
 async def get_swagger_response(url: str) -> dict:
-    '''Make request for procedure swagger.json.
+    """
+    Make request for procedure swagger.json.
 
     Args:
         url(str): url
 
     Returns:
         dict: Data
-    '''
+    """
     response = await async_api_request.session.get(f"{url}{URL_SWAGGER_POSTFIX}")
     if response.ok:
         data = await response.json()
@@ -56,8 +59,9 @@ async def get_swagger_response(url: str) -> dict:
 
 @retry(reraise=True, stop=stop_after_attempt(10), wait=wait_fixed(1.5))
 async def get_swagger_on_startup(url, doc_type) -> None:
-    '''
+    """
     Starts on app startup
+
     Save cached swagger data locally as dict
 
     Returns:
@@ -65,7 +69,7 @@ async def get_swagger_on_startup(url, doc_type) -> None:
 
     Raise:
         Exceptions: if service url isn't available
-    '''
+    """
     try:
         if data := await get_swagger_response(url):
             with cached_swagger_full_path(doc_type).open('w') as fl:
@@ -79,7 +83,8 @@ async def get_swagger_on_startup(url, doc_type) -> None:
 
 
 async def get_swagger(url, doc_type) -> dict:
-    '''Get swagger data for view.
+    """
+    Get swagger data for view.
 
     Args:
         url(str): service url
@@ -90,7 +95,7 @@ async def get_swagger(url, doc_type) -> dict:
 
     Raises:
         web.HTTPNotFound: if service doesn't exist or not allowed
-    '''
+    """
     try:
         if data := await get_swagger_response(url):
             return data

src/prozorro_doc/views.py

@@ -20,7 +20,7 @@ async def ping(request):
         responses:
             "200":
                 description: successful operation. Return "pong" json
-        """
+    """
     return web.json_response({'status': 'ok'}, status=200)