0

I wrote math documentation for a Python module using a template (Latex + Sphinx syntax). Now I need to verify that all the formulae are rendered correctly in HTML. Inside my Python project root folder I initiated a Sphinx project according to this tutorial: https://www.sphinx-doc.org/en/master/usage/quickstart.html

Sphinx-build runs smoothly ... but there is no documentation at all, just skeletons of HTML files. Whatever I tried for many hours does not work for me.

Question: given a Python project, how to generate a documentation using Sphinx with very basic settings?

I would appreciate step-by-step instructions. It turns out, some non-trivial tweaking of index.rst or conf.py files is required. First of all, Sphinx should be informed where to look for the Python source files, but how ...

As an example, I created a dummy project with 3 files that define some functions. Inside the project root folder, in command line I typed:

sphinx-quickstart
make html

Alternatively (does not work either):

sphinx-quickstart docs
cd docs
make html

Some skeleton structure appears in _build/html subfolder, but no documentation for the source files "file1.py", "file2.py", "file3.py".

I do not know how to attach the project, but every file looks like that:

import numpy as np

def my_function1(arr: np.ndarray) -> bool:
    """
    Does something anything.
    Args:
        arr: some array.
    Returns:
        always True.
    """
    print(arr.size)
    print(arr.shape)
    print(arr)
    return True

enter image description here

enter image description here

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Albert65
  • 39
  • 3
  • Can you provide a [Minimal Reproducible Example](https://stackoverflow.com/help/minimal-reproducible-example) ? For example : one file containing some documentation with Latex formulae in it, your Sphinx config and the commands you run. – Lenormju Feb 11 '22 at 11:19
  • 1
    Depending on your layout [this answer](https://stackoverflow.com/a/60159862) goes into some detail and [also this answer](https://stackoverflow.com/a/59951675). When it's working write some mathjax in the docstring and it will render. – bad_coder Feb 12 '22 at 23:55
  • It turns out the problem in my case is to generate any documentation at all. Even function description does not appear in any form in the out HTML structure. Math documentation would be the next step. – Albert65 Feb 13 '22 at 18:36
  • I followed the first link provided by @bad_coder and it works, including my math documentation! Thanks a lot! Although, not without problems - I had to tweak some generated files manually - the link gives a good starting point. I am wondering, why the official Sphinx documentation does not pay enough attention to the basic usage scenario. – Albert65 Feb 13 '22 at 20:51
  • @Albert65 There are proposals on GitHub about writing a "how to get started guide" I think the problem is that a guide would need to explain some fundamental concepts about Python, or none at all to keep it simple. – bad_coder Feb 13 '22 at 21:25

0 Answers0