Regression: Docs Aren't Generated From Python Source

[justin-f-perez]

Issue Type

• Bug report
• docs

Molecule and Ansible details

latest/NA

Desired Behavior

rst docs in python source code are rendered by the documentation generation system.

Actual Behaviour

Large amounts of documentation from the python source code are simply missing from latest that were not missing in previous versions. Code blocks in .rst files similar to this apparently render to an empty string:

.. autoclass:: molecule.some.module.Class()
   :undoc-members:

I have on several occasions found myself reading raw rst in the source code or referencing old documentation which is inconvenient and error-prone. In some instances, "missing" docs could be due to pieces of molecule being spun out into their own repositories (e.g., docker/podman drivers; related: #2854 ). However, even docs native to this repository seem to be missing.

Take for example the create command documented in molecule command line reference rendered from this usage.rst file.

Here is an old version of the rendered docs for the create command, the corresponding usage.rst, and the corresponding python source. The rst bits from the python source are properly rendered, and the generated documentation is much more complete.

[justin-f-perez]

Unfortunately, I can't spend anymore time on this right now and I'm not familiar enough with the doc generation system to be more helpful. I see from tox.ini and setup.cfg that sphinx is the doc generation system and tox.ini appears to provide an entrypoint for building the docs locally. Furthermore, it appears the configuration file for sphinx is: https://github.com/ansible-community/molecule/blob/main/docs/conf.py It would be great if someone more familiar with tox and sphinx could take a look at this.

Assuming no one else resolves this within the next few weeks... It seems like the most reasonable place for me to start is by determining in which commit the regression was introduced. I'm unsure when this regression was introduced as the latest on readthedocs.io do not allow selecting older versions of the docs, and furthermore it would be good to know exactly which commit introduced it and not all commits will have generated documentation. Game plan:

1. learn how to generate docs locally so I can generate from old versions to check for this regression
2. determine in which commit this regression was introduced as this may provide clues about what the problem could be
3. read the sphinx docs, particularly sections related to the changes introduced in the regressing commit
4. make local modifications and test them

[ziegenberg]

I guess this is related to #3405.

[justin-f-perez]

/duplicate

[justin-f-perez]

oops too used to gitlab...