feat(docs): documentação automatizada com Sphinx, MyST, Redoc e deploy via GitHub Actions

Author: Diego-Espindola

.github/workflows/docs.yml

@@ -32,6 +32,10 @@ jobs:
         run: |
           python scripts/export_openapi.py app.main:app openapi.json
 
+      - name: Export OpenAPI JSON
+        run: |
+          python scripts/export_openapi.py app.main:app openapi.json
+
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:

docs/api.md

@@ -0,0 +1,7 @@
+# API
+
+Abaixo está a especificação OpenAPI do PyNewsServer:
+
+```{redoc}
+../openapi.json
+```

docs/conf.py

@@ -0,0 +1,45 @@
+# -- Project information -----------------------------------------------------
+project = "pynewsserver"
+author = "PyNews"
+
+# -- General configuration ---------------------------------------------------
+extensions = [
+    "myst_parser",
+    "sphinx_rtd_theme",
+    "sphinxcontrib.redoc",
+    "sphinx_copybutton",
+]
+
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "linkify",
+    "substitution",
+]
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+master_doc = "index"
+
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------------
+html_theme = "sphinx_rtd_theme"
+html_title = "Documentação - PyNewsServer"
+html_static_path = ['_static']
+
+# -- Options for sphinxcontrib-redoc -----------------------------------------
+redoc = [
+    {
+        "name": "OpenAPI",
+        "page": "api",
+        "spec": "../openapi.json",
+        "embed": True,
+        "opts": {
+            "hide-hostname": True
+        }
+    },
+]

docs/index.md

@@ -0,0 +1,9 @@
+# Documentação do PyNewsServer
+
+```{toctree}
+:maxdepth: 2
+:caption: Sumário
+
+readme
+api
+```

docs/readme.md

@@ -0,0 +1,5 @@
+<!-- Este arquivo será sobrescrito automaticamente pelo workflow do GitHub Actions. -->
+
+# PyNewsServer
+
+[README.md no GitHub](https://github.com/PythonFloripa/PyNewsServer?tab=readme-ov-file#pynewsserver)

requirements.txt

@@ -1,3 +1,11 @@
+# --- Dependências para documentação Sphinx ---
+sphinx>=7.0.0
+myst-parser>=2.0.0
+sphinx-rtd-theme>=2.0.0
+sphinx-copybutton>=0.5.2
+sphinxcontrib-redoc>=1.6.0
+linkify-it-py>=2.0.0
+# --- Fim dependências documentação ---
 aiosqlite==0.21.0 ; python_version >= "3.12" and python_version < "4.0"
 annotated-types==0.7.0 ; python_version >= "3.12" and python_version < "4.0"
 anyio==4.9.0 ; python_version >= "3.12" and python_version < "4.0"