neuroneural/autodoc

autodoc

The script autodoc-gen.sh is designed to automatically generate documentation for your packages using the Sphinx documentation generator.

How is this helpful?

One of the main advantages of using autodoc in conjunction with Sphinx is that it automatically generates ReStructured Text (.rst) files in a folder-wise manner. This means that the generated .rst files are organized in a structured folder hierarchy, which can greatly simplify the documentation website with each module having its toctree.

Another advantage of using autodoc is that it automatically removes unwanted headings and text such as Submodules, Subpackages, module, package and etc. Additionally autodoc displays the names of modules, submodules, and functions in a concise and readable format. For instance, when documenting a function like solve from the solver.py module within the neuro package, Sphinx would display it as neuro.solver.solve, whereas autodoc would only show solve. This reduction of unnecessary clutter helps improve the overall readability and aesthetics of the documentation.

Can't we achieve this by just using Sphinx?

Yes, we can do it with Sphinx but we need to modify each .rst file generated by Sphinx. This process is time-consuming and tedious, often taking hours or even days to modify each .rst file individually for large packages. Consequently, investing such a substantial amount of time in manual editing becomes inefficient and can be seen as a waste of valuable resources.

How to create documetation sites using autodoc?

Note Add __init__.py files in each and every folder which you need to document. Additionally add __init__.py file inside the project. For example if neuro is the project folder then add neuro/__init__.py

Step 1: Create docs directory inside the project folder where the source code is located.

mkdir docs

Step 2: Clone the repository.

git clone https://github.com/neuroneural/autodoc.git

Step 3: Run the script.

sh autodoc-gen.sh

Asks for User input. Enter Project name, Author name etc.

Step 4: Update index.rst Add all the module names(If you have added __init__.py file inside the project folder then just add project name)

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

Update conf.py a) Add this at the top of conf.py.

import os
import sys
                
sys.path.insert(0,os.path.abspath("../../"))
sys.path.insert(0,os.path.abspath("../"))

b) Add extentions

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.viewcode", # Remove if you don't want to display your code in documentation.
    "sphinx.ext.todo",
    "sphinx.ext.coverage",
    "sphinx.ext.mathjax",
    "sphinx.ext.githubpages",
    "sphinx.ext.napoleon",
    "sphinx.ext.autosummary",
    "sphinx.ext.inheritance_diagram",
    "sphinx.ext.intersphinx",
    "sphinx.ext.ifconfig",
    "sphinx_copybutton",
]

c) Customise your theme

html_theme = 'sphinx_rtd_theme'

Step 5: Build html files

make clean html

Step 6: Open index.html file inside _build/html to access the website.