workflow: ⚙️ add readme.io integration (#315)

.github/workflows/documentation.yml → .github/workflows/github-wiki-docs.yml

@@ -1,15 +1,14 @@
-name: documentation
+name: github-wiki-docs
 
 on:
   workflow_dispatch:
     inputs:
       version:
         description: 'Version to generate documentation for'
         required: true
-        default: 'latest'
 
 jobs:
-  build-and-publish-docs:
+  build-and-publish-github-wiki-docs:
     runs-on: ubuntu-latest
 
     steps:
@@ -29,7 +28,7 @@ jobs:
 
     - name: Generate documentation
       run: |
-          poetry run python docs/generate_docs.py
+        poetry run python docs/scripts/convert_docstrings_to_markdown.py
 
     - name: Clone wiki repository
       env:

.github/workflows/readmeio-docs.yml

@@ -0,0 +1,40 @@
+name: readmeio-docs
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to generate documentation for'
+        required: true
+
+jobs:
+  build-and-publish-readmeio-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v3
+
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.12'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install poetry
+        poetry install --no-root
+
+    - name: Generate documentation
+      run: |
+        poetry run python docs/scripts/convert_docstrings_to_markdown.py
+
+    - name: Apply readme.io metadata to markdown files
+      run: |
+        poetry run python docs/scripts/apply_metadata_to_markdown.py
+
+    - name: Publish documentation to readme.io
+      uses: readmeio/rdme@v8
+      with:
+        rdme: docs ./docs --key=${{ secrets.README_TOKEN }} --version=${{ inputs.version }}

docs/config/docstring-to-markdown-config.yml

@@ -0,0 +1,38 @@
+modules:
+  # --------------------- Views -----------------------
+  - input_path: "views/abstract_model_view"
+    output_path: "views/AbstractModelView.md"
+  - input_path: "views/list_model_view"
+    output_path: "views/ListModelView.md"
+  - input_path: "views/create_model_view"
+    output_path: "views/CreateModelView.md"
+  - input_path: "views/retrieve_model_view"
+    output_path: "views/RetrieveModelView.md"
+  - input_path: "views/update_model_view"
+    output_path: "views/UpdateModelView.md"
+  - input_path: "views/delete_model_view"
+    output_path: "views/DeleteModelView.md"
+  - input_path: "views/helpers/types"
+    output_path: "views/helpers/Types.md"
+
+  # -------------------- Viewsets ---------------------
+  - input_path: "viewsets/model_viewset"
+    output_path: "viewsets/ModelViewSet.md"
+  - input_path: "viewsets/base_model_viewset"
+    output_path: "viewsets/BaseModelViewSet.md"
+
+  # -------------------- Testing ----------------------
+  - input_path: "testing/core/components/headers"
+    output_path: "testing/core/components/Headers.md"
+  - input_path: "testing/core/components/path_parameters"
+    output_path: "testing/core/components/PathParameters.md"
+  - input_path: "testing/core/components/payloads"
+    output_path: "testing/core/components/Payloads.md"
+  - input_path: "testing/core/components/query_parameters"
+    output_path: "testing/core/components/QueryParameters.md"
+  - input_path: "testing/viewsets/model_viewset_test_case"
+    output_path: "testing/viewsets/ModelViewSetTestCase.md"
+
+settings:
+  project_root: ninja_crud
+  markdown_root: docs/reference

docs/config/readmeio-config.yml

@@ -0,0 +1,84 @@
+docs:
+  # -------------------- Guides -----------------------
+  - title: "Introduction"
+    excerpt: "Overview of Django Ninja CRUD"
+    categorySlug: "documentation"
+    path: "docs/guides/01-Introduction.md"
+  - title: "Installation"
+    excerpt: "How to install Django Ninja CRUD"
+    categorySlug: "documentation"
+    path: "docs/guides/02-Installation.md"
+  - title: "Setup"
+    excerpt: "How to setup Django Ninja CRUD"
+    categorySlug: "documentation"
+    path: "docs/guides/03-Setup.md"
+  - title: "Examples"
+    excerpt: "Quick examples of how to use Django Ninja CRUD"
+    categorySlug: "documentation"
+    path: "docs/guides/04-Examples.md"
+
+  # ------------------- Reference ---------------------
+  # --------------------- Views -----------------------
+  - title: "AbstractModelView"
+    excerpt: "Abstract class for CRUD views"
+    categorySlug: "reference"
+    path: "docs/reference/views/AbstractModelView.md"
+  - title: "ListModelView"
+    excerpt: "List view for CRUD views"
+    categorySlug: "reference"
+    path: "docs/reference/views/ListModelView.md"
+  - title: "CreateModelView"
+    excerpt: "Create view for CRUD views"
+    categorySlug: "reference"
+    path: "docs/reference/views/CreateModelView.md"
+  - title: "RetrieveModelView"
+    excerpt: "Retrieve view for CRUD views"
+    categorySlug: "reference"
+    path: "docs/reference/views/RetrieveModelView.md"
+  - title: "UpdateModelView"
+    excerpt: "Update view for CRUD views"
+    categorySlug: "reference"
+    path: "docs/reference/views/UpdateModelView.md"
+  - title: "DeleteModelView"
+    excerpt: "Delete view for CRUD views"
+    categorySlug: "reference"
+    path: "docs/reference/views/DeleteModelView.md"
+  - title: "Types"
+    excerpt: "Types for CRUD views"
+    categorySlug: "reference"
+    path: "docs/reference/views/helpers/Types.md"
+
+  # -------------------- Viewsets ---------------------
+  - title: "ModelViewSet"
+    excerpt: "ModelViewSet for CRUD viewsets"
+    categorySlug: "reference"
+    path: "docs/reference/viewsets/ModelViewSet.md"
+  - title: "BaseModelViewSet"
+    excerpt: "BaseModelViewSet for CRUD viewsets"
+    categorySlug: "reference"
+    path: "docs/reference/viewsets/BaseModelViewSet.md"
+
+  # -------------------- Testing ----------------------
+  # --------------------- Core ------------------------
+  - title: "Headers"
+    excerpt: "Headers for testing"
+    categorySlug: "reference"
+    path: "docs/reference/testing/core/components/Headers.md"
+  - title: "PathParameters"
+    excerpt: "PathParameters for testing"
+    categorySlug: "reference"
+    path: "docs/reference/testing/core/components/PathParameters.md"
+  - title: "Payloads"
+    excerpt: "Payloads for testing"
+    categorySlug: "reference"
+    path: "docs/reference/testing/core/components/Payloads.md"
+  - title: "QueryParameters"
+    excerpt: "QueryParameters for testing"
+    categorySlug: "reference"
+    path: "docs/reference/testing/core/components/QueryParameters.md"
+
+  # -------------------- Viewsets ---------------------
+  - title: "ModelViewSetTestCase"
+    excerpt: "ModelViewSetTestCase for testing"
+    categorySlug: "reference"
+    path: "docs/reference/testing/viewsets/ModelViewSetTestCase.md"

docs/scripts/apply_metadata_to_markdown.py

@@ -0,0 +1,44 @@
+import logging
+
+import frontmatter
+import yaml
+
+READMEIO_CONFIG_PATH = "docs/config/readmeio-config.yml"
+
+
+def load_yaml_file(file_path: str):
+    """Load and return the YAML configuration from the given file path."""
+    with open(file_path) as yaml_file:
+        return yaml.load(yaml_file, Loader=yaml.FullLoader)
+
+
+def apply_metadata_to_markdown(markdown_file_path: str, metadata: dict):
+    """Apply metadata from readmeio-config to the markdown files."""
+    try:
+        # Read the existing Markdown file
+        post = frontmatter.load(markdown_file_path)
+
+        # Update the frontmatter with the metadata
+        post.metadata = metadata
+
+        # Write the updated Markdown file
+        frontmatter.dump(post, markdown_file_path)
+    except FileNotFoundError:
+        logging.error(f"Markdown file not found: {markdown_file_path}")
+    except Exception as e:
+        logging.error(f"Error applying metadata to {markdown_file_path}: {e}")
+        raise e
+
+
+def main():
+    """Apply metadata to the Markdown files."""
+    readmeio_config = load_yaml_file(READMEIO_CONFIG_PATH)
+
+    for doc in readmeio_config["docs"]:
+        markdown_file_path = doc.pop("path")
+        apply_metadata_to_markdown(markdown_file_path=markdown_file_path, metadata=doc)
+
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+    main()

docs/scripts/convert_docstrings_to_markdown.py

@@ -0,0 +1,62 @@
+import logging
+import os
+import subprocess
+
+import yaml
+
+GLOBAL_CONFIG_PATH = "docs/config/docstring-to-markdown-config.yml"
+PYDOC_MARKDOWN_CONFIG_PATH = "docs/config/pydoc-markdown-config.yml"
+
+
+def load_yaml_file(file_path: str):
+    """Load and return the YAML configuration from the given file path."""
+    with open(file_path) as yaml_file:
+        return yaml.load(yaml_file, Loader=yaml.FullLoader)
+
+
+def convert_docstrings_to_markdown(
+    input_path: str, output_path: str, markdown_config: dict
+):
+    """Convert the docstrings in the given input path to Markdown and save to the given output path."""
+    try:
+        # Create the output directory if it doesn't exist
+        os.makedirs(os.path.dirname(output_path), exist_ok=True)
+
+        # Update the output path in the markdown config
+        markdown_config["renderer"]["filename"] = output_path
+
+        # Generate the Markdown documentation
+        absolute_input_path = os.path.join(os.getcwd(), input_path)
+        subprocess.run(
+            [
+                "poetry",
+                "run",
+                "pydoc-markdown",
+                "-m",
+                absolute_input_path,
+                yaml.dump(markdown_config),
+            ]
+        )
+    except Exception as e:
+        logging.error(f"Error generating documentation for {input_path}: {e}")
+
+
+def main():
+    """Generate Markdown documentation for all modules in the project."""
+    global_config = load_yaml_file(GLOBAL_CONFIG_PATH)
+    pydoc_markdown_config = load_yaml_file(PYDOC_MARKDOWN_CONFIG_PATH)
+
+    settings = global_config["settings"]
+    for module in global_config["modules"]:
+        input_path = os.path.join(settings["project_root"], module["input_path"])
+        output_path = os.path.join(settings["markdown_root"], module["output_path"])
+        convert_docstrings_to_markdown(
+            input_path=input_path,
+            output_path=output_path,
+            markdown_config=pydoc_markdown_config,
+        )
+
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+    main()

pyproject.toml

@@ -49,6 +49,7 @@ coverage = "^6.5.0"
 pre-commit = "^2.20.0"
 pydoc-markdown = "^4.8.2"
 pyyaml = "^6.0.1"
+python-frontmatter = "^1.0.1"
 
 [tool.ruff]
 select = [