feat/dpcs: create api docs html template generator, fix bugs, improve docs

alexeev-prog · alexeev-prog · commit afc2300b2707 · 2024-11-13T22:55:27.000+07:00
diff --git a/Doxyfile b/Doxyfile
@@ -1,4 +1,4 @@
-# Doxyfile 1.12.0
+\# Doxyfile 1.12.0
 
 # This file describes the settings to be used by the documentation system
 # Doxygen (www.doxygen.org) for a project.
@@ -48,7 +48,7 @@ PROJECT_NAME           = "pyEchoNext"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = "0.5.5"
+PROJECT_NUMBER         = "0.5.6"
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
diff --git a/README.md b/README.md
@@ -41,8 +41,8 @@ Welcome to **EchoNext**, where innovation meets simplicity! Are you tired of the
 
 **Imagine** a lightweight framework that empowers you to create modern web applications with lightning speed and flexibility. With EchoNext, you're not just coding; you're building a masterpiece!
 
- > Last unstable version: 0.5.5 alpha
- > Last stable version: 0.5.4 alpha
+ > Last unstable version: 0.5.6 alpha
+ > Last stable version: 0.5.5 alpha
 
 ## 🤔 Why Choose SqlSymphony?
 
diff --git a/SECURITY.md b/SECURITY.md
@@ -7,6 +7,7 @@ currently being supported with security updates.
 
 | Version | Supported          |
 | ------- | ------------------ |
+| 0.5.6   | :white_check_mark: |
 | 0.5.5   | :white_check_mark: |
 | 0.5.4   | :white_check_mark: |
 | 0.5.3   | :white_check_mark: |
diff --git a/docs/ru/article1.md b/docs/ru/article1.md
diff --git a/docs/ru/index.md b/docs/ru/index.md
@@ -10,5 +10,6 @@
 
 ## Дополнительные материалы
 
+ + [Как создать свой веб-фреймворк на Python](./article1.md)
  + [ASGI Documentation](https://asgi.readthedocs.io/_/downloads/en/stable/pdf/)
  + [PEP 333](https://peps.python.org/pep-0333/#the-application-framework-side)
diff --git a/docs/ru/webframework_design.md b/docs/ru/webframework_design.md
@@ -7,9 +7,13 @@
  + Обработчики маршрутизации (routes):
    - Простые: `/index`
    - Параметризованные: `/article/{article_id}`
- + Обработчики запросов (views, handlers).
+ + Обработчики запросов (views).
+ + Middleware
+ + Request/Response
+ + i18n/l10n
+ + Конфигурация
 
-Основное требование: веб-фреймворк должен поддерживаться быстрым, легким и эффективным сервером (например gunicorn). Для этого в Python есть руководство по WSGI.
+Основное требование: веб-фреймворк должен поддерживаться быстрым, легким и эффективным сервером (например gunicorn). Для этого в Python есть руководство по WSGI - [PEP 333](https://peps.python.org/pep-0333/#the-application-framework-side).
 
 ## Устройство веб-сервера на Python
 
diff --git a/examples/example_locale.py b/examples/example_locale.py
@@ -8,7 +8,7 @@
 from pyechonext.template_engine.jinja import render_template
 from pyechonext.middleware import middlewares
 from pyechonext.docsgen import ProjDocumentation
-from pyechonext.apidoc_ui import APIDocumentation
+from pyechonext.apidoc_ui import APIDocumentation, APIDocUI
 
 
 class UsersView(View):
@@ -41,7 +41,8 @@ def post(self, request, response, **kwargs):
 
 @echonext.route_page('/api-docs')
 def api_docs(request, response):
-	return Response(request, content_type='application/json', body=apidoc.generate_spec())
+	ui = APIDocUI(apidoc.generate_spec())
+	return ui.generate_html_page()
 
 
 @echonext.route_page("/book")
diff --git a/examples/example_locale/docs/api/Initiation-Project_example_locale.md b/examples/example_locale/docs/api/Initiation-Project_example_locale.md
@@ -1,8 +1,8 @@
 # Initiation-Project example_locale
 Project Documentation for example_locale
 
- + *Creation date*: 2024-11-12 23:30:10
- + *Modification date*: 2024-11-12 23:30:10
+ + *Creation date*: 2024-11-13 19:23:55
+ + *Modification date*: 2024-11-13 19:23:55
 
 ## Routes
 /api-docs, /book
@@ -12,7 +12,7 @@ Project Documentation for example_locale
 ## Subsections
 
 ### /book
-Creation date: 2024-11-12 23:30:10
+Creation date: 2024-11-13 19:23:55
 
 #### Route
 Methods: ['GET', 'POST']
diff --git a/pyechonext/apidoc_ui/__init__.py b/pyechonext/apidoc_ui/__init__.py
@@ -1,3 +1,4 @@
 from pyechonext.apidoc_ui.api_documentation import APIDocumentation
+from pyechonext.apidoc_ui.ui import APIDocUI
 
-all = APIDocumentation
+all = [APIDocumentation, APIDocUI]
diff --git a/pyechonext/apidoc_ui/api_documentation.py b/pyechonext/apidoc_ui/api_documentation.py
@@ -41,12 +41,23 @@ def generate_spec(self) -> str:
 		for url in self._app.urls:
 			spec["paths"][url.url] = {
 				"get": {
-					"summary": str(url.view.__doc__)
-					.strip()
-					.replace("\n", ".")
-					.replace("\t", ";"),
-					"responses": {"200": {"description": "Successful response"}},
-				}
+					"summary": str(f"{url.view.__doc__}. {url.view.get.__doc__}")
+					.replace("\n", "<br>")
+					.strip(),
+					"responses": {
+						"200": {"description": "Successful response"},
+						"405": {"description": "Method not allow"},
+					},
+				},
+				"post": {
+					"summary": str(f"{url.view.__doc__}. {url.view.post.__doc__}")
+					.replace("\n", "<br>")
+					.strip(),
+					"responses": {
+						"200": {"description": "Successful response"},
+						"405": {"description": "Method not allow"},
+					},
+				},
 			}
 
 		for path, handler in self._app.routes.items():
@@ -56,8 +67,21 @@ def generate_spec(self) -> str:
 					.strip()
 					.replace("\n", ".")
 					.replace("\t", ";"),
-					"responses": {"200": {"description": "Successful response"}},
-				}
+					"responses": {
+						"200": {"description": "Successful response"},
+						"405": {"description": "Method not allow"},
+					},
+				},
+				"post": {
+					"summary": str(handler.__doc__)
+					.strip()
+					.replace("\n", ".")
+					.replace("\t", ";"),
+					"responses": {
+						"200": {"description": "Successful response"},
+						"405": {"description": "Method not allow"},
+					},
+				},
 			}
 
 		return spec
diff --git a/pyechonext/apidoc_ui/ui.py b/pyechonext/apidoc_ui/ui.py
@@ -0,0 +1,222 @@
+class APIDocUI:
+	"""
+	This class describes an api document ui.
+	"""
+
+	def __init__(self, specification: dict):
+		"""
+		Constructs a new instance.
+
+		:param		specification:	The specification
+		:type		specification:	dict
+		"""
+		self.specification = specification
+
+	def generate_section(
+		self,
+		route: str,
+		summary_get: str,
+		summary_post: str,
+		get_responses: dict,
+		post_responses: dict,
+	) -> str:
+		"""
+		generate section
+
+		:param		route:			 The route
+		:type		route:			 str
+		:param		summary_get:	 The summary get
+		:type		summary_get:	 str
+		:param		summary_post:	 The summary post
+		:type		summary_post:	 str
+		:param		get_responses:	 The get responses
+		:type		get_responses:	 dict
+		:param		post_responses:	 The post responses
+		:type		post_responses:	 dict
+
+		:returns:	template section
+		:rtype:		str
+		"""
+
+		template = f"""
+<div class="section">
+		<div class="section-header">
+			<span>{route}</span>
+			<span class="collapse-icon">➡️</span>
+		</div>
+		<div class="section-content">
+			<div class="method">
+				<strong>GET</strong>
+				<p>{summary_get}</p>
+				<div class="responses">
+					{"".join([f"<div class='response-item'>{key}: {value["description"]}.</div>" for key, value in get_responses.items()])}
+				</div>
+			</div>
+			<div class="method">
+				<strong>POST</strong>
+				<p>{summary_post}</p>
+				<div class="responses">
+					<div class="responses">
+					{"".join([f"<div class='response-item'>{key}: {value["description"]}.</div>" for key, value in post_responses.items()])}
+				</div>
+				</div>
+			</div>
+		</div>
+	</div>
+				   """
+
+		return template
+
+	def generate_html_page(self) -> str:
+		"""
+		Generate html page template
+
+		:returns:	template
+		:rtype:		str
+		"""
+		template = """
+<!DOCTYPE html>
+<html lang="en">
+<head>
+	<meta charset="UTF-8">
+	<meta name="viewport" content="width=device-width, initial-scale=1.0">
+	<title>API Documentation</title>
+	<style>
+		body {
+			font-family: Arial, sans-serif;
+			margin: 0;
+			padding: 0;
+			background-color: #f9f9f9;
+			color: #333;
+		}
+		h1, h2, h3 {
+			margin: 0;
+			padding: 10px 0;
+		}
+		.container {
+			max-width: 800px;
+			margin: 40px auto;
+			padding: 20px;
+			background: #fff;
+			border-radius: 8px;
+			box-shadow: 0 2px 15px rgba(0, 0, 0, 0.1);
+		}
+		.version {
+			font-size: 14px;
+			color: #555;
+			margin-bottom: 20px;
+		}
+		.info-section {
+			border-bottom: 1px solid #ddd;
+			padding-bottom: 20px;
+			margin-bottom: 20px;
+		}
+		.section {
+			border-radius: 5px;
+			overflow: hidden;
+			margin-bottom: 20px;
+			transition: box-shadow 0.3s ease;
+		}
+		.section-header {
+			padding: 15px;
+			background: #007bff;
+			color: white;
+			cursor: pointer;
+			position: relative;
+			font-weight: bold;
+			display: flex;
+			justify-content: space-between;
+			align-items: center;
+		}
+		.section-content {
+			padding: 15px;
+			display: none;
+			overflow: hidden;
+			background-color: #f1f1f1;
+		}
+		.method {
+			border-bottom: 1px solid #ddd;
+			padding: 10px 0;
+		}
+		.method:last-child {
+			border-bottom: none;
+		}
+		.responses {
+			margin-top: 10px;
+			padding-left: 15px;
+			font-size: 14px;
+			color: #555;
+		}
+		.response-item {
+			margin-bottom: 5px;
+		}
+		.collapse-icon {
+			transition: transform 0.3s;
+		}
+		.collapse-icon.collapsed {
+			transform: rotate(90deg);
+		}
+		.section:hover {
+			box-shadow: 0 4px 20px rgba(0, 0, 0, 0.15);
+		}
+	</style>
+</head>
+<body>
+
+<div class="container">
+	<h1>OpenAPI Documentation</h1>
+	<h2>PyEchoNext Web Application</h2>
+	<div class="version">OpenAPI Version: {{openapi-version}}</div>
+	<div class="info-section">
+		<h2>Application Information</h2>
+		<p><strong>Title:</strong> {{info_title}}</p>
+		<p><strong>Version:</strong> {{info_version}}</p>
+		<p><strong>Description:</strong> {{info_description}}</p>
+	</div>
+
+	{{sections}}
+
+<script>
+	document.querySelectorAll('.section-header').forEach(header => {
+		header.addEventListener('click', () => {
+			const content = header.nextElementSibling;
+			const icon = header.querySelector('.collapse-icon');
+
+			if (content.style.display === "block") {
+				content.style.display = "none";
+				icon.classList.add('collapsed');
+			} else {
+				content.style.display = "block";
+				icon.classList.remove('collapsed');
+			}
+		});
+	});
+</script>
+
+</body>
+</html>
+				   """
+
+		content = {
+			"{{openapi-version}}": self.specification["openapi"],
+			"{{info_title}}": self.specification["info"]["title"],
+			"{{info_version}}": self.specification["info"]["version"],
+			"{{info_description}}": self.specification["info"]["description"],
+			"{{sections}}": "\n".join(
+				[
+					self.generate_section(
+						path,
+						value["get"]["summary"],
+						value["post"]["summary"],
+						value["get"]["responses"],
+						value["post"]["responses"],
+					)
+					for path, value in self.specification["paths"].items()
+				]
+			),
+		}
+
+		for key, value in content.items():
+			template = template.replace(key, value)
+
+		return template
diff --git a/pyechonext/app.py b/pyechonext/app.py
@@ -304,6 +304,11 @@ def switch_i18n_locale(self, locale: str, locale_dir: str):
 		self.i18n_loader.translations = self.i18n_loader.load_locale(
 			self.i18n_loader.locale, self.i18n_loader.directory
 		)
+		self.l10n_loader.locale = locale
+		self.l10n_loader.directory = directory
+		self.i18n_loader.locale_settings = self.l10n_loader.load_locale(
+			self.l10n_loader.locale, self.l10n_loader.directory
+		)
 
 	def __call__(self, environ: dict, start_response: method) -> Iterable:
 		"""
diff --git a/pyproject.toml b/pyproject.toml
