How to build Sphinx documentation to list Functions/Methods with parameters and expected returns?

FilBot3 commented 4 years ago

Is there a way to use Sphinx to build documentation that would list the Function/Methods, their parameters, and expected returns? Using pydoc doesn't seem to format the docstrings properly.

Also, if it were made using something like this:

it might be easier to decipher.

FilBot3 commented 4 years ago

Anyone? Bueller?

symplrdudley commented 1 year ago

I guess this isn't going to get any looks.

symplrdudley commented 1 year ago

Clone repository

git clone git@github.com:microsoft/azure-devops-python-api.git

Then change directories into the project.

Install

python -m pip install sphinx

Setup docs folder

sphinx-quickstart \
  --sep \
  --project "azure-devops" \
  --author "Microsoft" \
  --release "2023" \
  --language "en" \
  --ext-autodoc \
  --makefile \
  ./docs

This will put the config and other files into the docs/ folder.

Configuration of Sphinx

Open docs/conf.py. Add the following lines towards the top.

import os
import sys

sys.path.insert(0, os.path.abspath('../../azure-devops/azure'))

[!Warning] Path inserts I'm still working on what to do with this. So far it's not working as I remember.

Add Sphinx extensions

Open docs/conf.py and add the following lines to extensions.

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon' # Needs to be installed.
]

Build API Docs in rST

sphinx-apidoc --force --output-dir source ../azure-devops/azure

If you're using split directories, then instead of ., you would put the output into source.

Modify the index.rst

Add the sections with ++.

.. azure-devops documentation master file, created by
   sphinx-quickstart on Mon May  1 13:42:46 2023.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to azure-devops's documentation!
========================================

++ .. automodule:: azure.devops
++   :members:
++   :undoc-members:
++   :show-inheritance:

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

++   modules

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

The only piece that is truly desired is the modules directive on the same indentation as toctree.

Build API Docs in HTML

You need to do the [[#Build API Docs in rST]] first, then you can perform this step.

make html

Now the HTML documentation should be available in build/html/index.html.

microsoft / azure-devops-python-api