🔒 Auto generate all Sphinx rst files

[shrewd fractal]

Hi everyone, I'm doing some trail blazing work at my org and I want to find a way to have sphinx autogenerate all documentation from my library module. I can't quite find a way to do this. I'm use to the rust's world cargo doc that just works, so I'm a little confused by how it seems like most documentation has to be manually written in rst files.

[humble cedar]

@shrewd fractal

Python help channel opened

Remember to:

• Ask your Python question, not if you can ask or if there's an expert who can help.
• Show a code sample as text (rather than a screenshot) and the error message, if you've got one.
• Explain what you expect to happen and what actually happens.

:warning: Do not pip install anything that isn't related to your question, especially if asked to over DMs.

Closes after a period of inactivity, or when you send !close.

[small plume]

You can look into enabling the sphinx.ext.autodoc extension.

[shrewd fractal]

I did that...

give me a sec

[shrewd fractal]

maybe I missed something?

import os
import sys

sys.path.insert(0, os.path.abspath("../.."))  # Points to my_project/

# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = "Timestamp"
copyright = "2025-Present, corp"
author = "myname"
release = "0.0.1"

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

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

autosummary_generate = True  # Always generate autosummary
autodoc_default_options = {
    "members": True,
    "inherited-members": True,
    "show-inheritance": True,
}

templates_path = ["_templates"]
exclude_patterns = []


# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = "python_docs_theme"
html_static_path = ["_static"]

[small plume]

conf looks correct. The only other thing you'll want to do is in to invoke autodoc inside your RST files. For example:

.. automodule:: foo.bar
    :members:

will document every public member in foo.bar with a docstring applied to it.
You can also document each thing individually. The clauses you can document are listed in the docs I linked earlier.

[shrewd fractal]

ohh, I thought rst was a markup language, I didn't think you could write expressions with it

[small plume]

That .. automodule:: part is what ReStructuredText calls a directive if you want to look more into it.

[shrewd fractal]

Okay I got that working, maybe my modules aren't exported

This is what you need for a normal python library right?

└── timestamp
    ├── __init__.py
    └── parser.py

this is a tiny library, but init is empty and parser has an enum and a function I want to publicly export

[small plume]

Seems correct. For that you'd just do .. automodule:: timestamp.parser plus the :members: part and it should be able to document it.

I'll assume that you're using docstrings such as this one which is what would be picked up by autodoc.

def parse(string, option, ...):
  """Parses the string using options..."""
  ...

If the member doesn't have a docstring but you still want to show it via autodoc, you'd need to add the :undoc-members: option (or include it explicitly using one of the other autodoc directives).

[shrewd fractal]

so for every module I'll need a ```rst
.. automodule:: lib.module1
:members:
.. automodule:: lib.module2
:members:

right?

and also how do I control the output of doc items, I'm confused how it did this. Because in my code I have a class, function, then expectations defined in that order. However the documentation did them in expectations, class, expectations, function

[small plume]

Yeah.

[small plume]

The order is alphabetical by default. You can control it with the :member-order: option.

[shrewd fractal]

okay I think my last two questions are, how do I esacpe literal characters in docs like : in my comments? and how do I refer to other python types within the docs as an inline?

like ```py
#: uses datetime.datatime

refers to python's datetime module then class

[small plume]

For this one, you can use a cross reference as seen here (the :py at the start isn't necessary). For example:

Returns a :class:`foo.bar.Baz` instance.

would replace that :class: part with a link to that particular class in the docs. For things that aren't part of your module such as datetime, however, you'll need to add the intersphinx extension with a mapping in your conf file to the external documentation being referenced (assuming it is documented with Sphinx which most are).

For escaping, you can add a backslash before the character to escape. If your editor complains about an invalid escape sequence, adding another backslash before should also work. In your case, it should already escape the colon since Sphinx treats #: as doc-comments.

[humble cedar]

Python help channel closed for inactivity

This help channel has been closed. Feel free to create a new post in #1035199133436354600. To maximize your chances of getting a response, check out this guide on asking good questions.