Auto-documentation setup using Sphinx

1_autodoc.md

Setup Sphinx

Note: Google style / Numpy style for docstrings should be used for this example. Check it here

Requirements

• pip install sphinx
• pip install myst-parser # To parse markdown files
• pip install sphinx-rtd-theme # or any theme

Initial Setup

• mkdir docs
• cd docs
• sphinx-quickstart

Configure conf.py

import os
import sys
sys.path.insert(0, os.path.abspath('..')) # Change to point to the parent folder of your app

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx.ext.napoleon',
    'myst_parser',
]

html_theme = 'sphinx_rtd_theme'

Build the doc files

sphinx-apidoc -o docs/source parent_folder_name/

Add modules to index.rst in case you need them

Welcome to XXXXX's documentation!
=========================================

This Framework contains automated test cases written in robotframework.

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules

Generate the html

cd docs/source
./make.bat html

Update the doc/html

sphinx-apidoc -o docs/source parent_folder_name/  # make sure it doesn't erase custom stuff we have in source
./make.bat clean; ./make.bat html

Access the html files

/build/html/index.html

Auto update and serve the doc using the supplied app.py

mkdir serve

copy the update.bat and app.py to the folder

./update.bat

2_app.py

# -*- coding: utf-8 -*-
"""Example lightweight backend to host the Sphinx generated documentation"""

from flask import Flask, Response

app = Flask(__name__, static_folder="../build/html/")

@app.route('/')
@app.route('/<path:filename>')
def sphinx_documentation(filename: str='index.html') -> Response:
    """Serve Sphinx documentation

    Args:
        filename (str, optional): Serve static html files depending on the requested url. Defaults to 'index.html'.

    Returns:
        Response: Flask's base response class
    """
    
    return app.send_static_file(filename)

if __name__ == "__main__":
    app.run(debug=True, host="0.0.0.0")

3_update.bat

@ECHO OFF

ECHO Updating the auto documentation

cd ..

call ./make.bat clean

call ./make.bat html

ECHO Launching the doc server

cd serve

py app.py

ECHO Finished updating the documentation

4_gitlab-ci.yml

stages:
  - image
  - deploy

image: busybox

pages:
  stage: deploy
  script:
    - mkdir public
    - cp -r DOCS/build/html/. public # specify build/html directory path
  artifacts:
    paths:
      - public
  only:
    - main # specify branch to run pages in