As M2R is deprecated in Sphinx3. I tried to use recommonmark in order to include README.md to my documentation.
I have the following structure
project
|--README.md
|--docs
|--|--conf.py
|--|--index.rst
|--|--...
In conf.py I added recommonmark to extensions. and have '.md' in the source_suffix
In the index.rst
I have
.. toctree::
:maxdepth: 2
../README.md
modules
But Sphinx couldn't find it:
WARNING: toctree contains reference to nonexisting document 'README'
I can solve it by creating a softlink of README to the docs folder. But this doesn't seem quite right for version control. As I worries the build will break on other machines, or in future changes of configuration.
So is there a way to include README.md from the project directory to index.rst?
Many thanks
You can use an indirection.
index.rst
.. toctree::
readme
readme.rst
.. include:: ../README.md
Pyramid docs do this.
Related
I have a project including a Python package as well as some Matlab code, which should all go into the same documentation created by Sphinx.
The Python part of the documentation works flawlessly quite some time already - the Matlab part was added now and makes some trouble.
The data structure more or less is as follows:
|- python
|- modules
|- including subpackages
|- some sub-modules
|- matlab
|- scripts
|- functions
|- docs
|- source
|- conf.py
|- matlab.rst
|- python.rst
|- index.rst
|- ...
The most relevant lines in conf.py are prob. the following:
import os
import sys
# for the Python autodoc package
sys.path.insert(0, os.path.abspath('../..'))
extensions = ['sphinx.ext.napoleon', 'sphinxcontrib.matlab', 'sphinx.ext.autodoc']
# Path to the Matlab files
matlab_src_dir = '../../matlab'
#matlab_src_dir = '<<abssolute_path>>/matlab'
As you see, I tried both relative and absolute paths for matlab_src_dir. So far, without any difference.
The python.rst, which was created automatically by apidoc, contains:
python package
==============
.. automodule:: python
:members:
:undoc-members:
:show-inheritance:
Subpackages
-----------
.. toctree::
:maxdepth: 4
python.subpackages
The matlab.rst was created manually and contains:
matlab package
==============
.. mat:automodule:: matlab
:members:
:undoc-members:
:show-inheritance:
Subscripts
----------
.. toctree::
:maxdepth: 4
matlab.function_file
Thus, python.rst and matlab.rst are more or less the same but with mat:automodule for Matlab according to the documentation.
Finally, index.rst contains:
.. toctree::
:maxdepth: 2
python
.. toctree::
:maxdepth: 2
matlab
Now, when I run Sphinx' make html I receive the following error, which results in a nice Python documentation but an empty Matlab documentation:
WARNING: [sphinxcontrib-matlabdomain]: failed to import module 'matlab'; the following exception was raised:
Traceback (most recent call last):
File "C:\Users\<<username>>\AppData\Roaming\Python\Python39\site-packages\sphinxcontrib\mat_documenters.py", line 117, in import_object
obj = self.module = modules[self.modname]
KeyError: 'matlab'
What am I missing here. Why can't Sphinx find the matlab folder with the containing m-files?
And if that should be solved, maybe a secondary question: is there any similar function as apidoc for Matlab files, so that I do not need to create all *.rst files myself?
Thank you for any hints!
BTW: I am running on Sphinx v4.4.0 under Python 3.9.7.
Neither providing a hard-coded absolute path to matlab_src_dir nor providing os.path.abspath(relative_path) lead to success.
Thanks to Steve Piercy, who mentioned an example in the comments, I found that I should use os.path.dirname(os.path.abspath(relative_path)). As such, the errors are gone and Sphinx is working.
This is interesting, because I have already tried os.path.abspath(relative_path to the parent of the package) before, which I would expect is doing the same than os.path.dirname(). Anyway, I got a working solution now.
If anybody would have an idea about the second question ("is there any similar function as apidoc for Matlab files, so that I do not need to create all *.rst files myself?") I would be really happy.
I am autogenerating documentation for a Python package using Sphinx with the autodoc extension. The issue I am facing is that the autodoc skips any modules with an underscore.
Some modules were underscored to discourage users from importing them. However, the classes inside these underscored files have no underscores.
When I add the underscored module manually to the package_name.rst and ran make html, it shows. So my problem is how to automate that from autodoc.
I am trying to avoid parsing the package_name.rst via a script to add them. I am hoping for an autodoc flag or a hack!
It's perhaps a misconception to think the ..automodule :: directive applied to a package will automatically document sub-modules as members (by comparison with classes, variables, etc).
I just tested this but it can not be done using :private-members: and or :special-members:. Not by writing either option in the .. automodule:: directive corresponding to the package. (Trying to set both options in autodoc_default_options gives the same result.)
The following example of package and module layout:
C:.
│
└────your_package
│
│ public_module.py
│ _private_module.py
│ __init__.py
Using a .rst with a single .. automodule:: for the package:
Your package rst
================
.. automodule:: your_package
:members:
:undoc-members:
:private-members:
:special-members:
Minimal example _private_module.py with docstrings (public_module.py is the same except for the title):
"""Private module docstring."""
class PublicClass:
"""Docstring."""
pass
Does indeed give an empty documentation:
But if you remove the underscore from the module you get the exact same result.
I am trying to avoid parsing the package_name.rst via a script to add them
If you are generating the .rst files with sphinx-apidoc if using the -P flag:
-P, --private
Include “_private” modules.
New in version 1.2.
The generated files will include an .. automodule:: directive for the private modules, this does have the side-effect of also including the :private-members: option as noted in another post "Include __main__.py in sphinx-apidoc generated files".
Example explicitly including the .. automodule:: directives:
Your package rst
================
.. automodule:: your_package
:members:
:undoc-members:
.. automodule:: your_package.public_module
:members:
:undoc-members:
.. automodule:: your_package._private_module
:members:
:undoc-members:
The result:
I'm wondering where shall I put my non-python files (DLL, .c, .cpp). Currently I keep it in 'resources' folder under my package destination:
my_project/
docs\
my_pkg/
resources/
API.dll
__init__.py
module.py
tests\
test_module
.gitignore
README.md
MANIFEST.in
requirements.txt
setup.py
I want to know what is Pythonic way?
Perfect place, see Python Packaging Guide. Don't forget to put the files into setup.py or MANIFEST.in.
The path to the master doc of a Sphinx build can be specified in conf.py. However, this directory path is reflected in the generated HTML, and shows for example in Read The Docs as a missing index. I'd like to use this alternative path to structure my project cleanly - to have configuration at the top level and documentation inside src, but have the build essentially get rid of it.
So here's what I had previously:
docs
conf.py
index.rst
things
doc1.rst
doc2.rst
This works, but when lots of files are added to the top level, it gets messy with Sphinx's makefiles etc. I'd like to have this instead:
docs
conf.py
src
index.rst
things
doc1.rst
doc2.rst
Which builds, but index.html is in build/html/src instead of build/html. I was surprised to find no information on this, other than the fact that master_doc in conf.py controls the location and name of the main file. How could I get my documentation to be built to build/html?
There is an option for specifying the location of the configuration file: -c.
# conf.py
master_doc = 'index'
# structure
docs
conf.py
src
index.rst
...
Then run sphinx-build -b html -c . src build/html. However, this solution indeed needs control over the build command, which is not available in Read The Docs. And it seems that -c doesn't work in Sphinx's own makefiles either (with -M instead of -b).
I used the sphinx-quickstart to set everything up. I used doc/ for the documentation root location. The folder containing my package is setup as:
myfolder/
doc/
mypackage/
__init__.py
moprob.py
...
After the quick start, I edited the path in conf.py to be:
import os
import sys
sys.path.insert(0, os.path.abspath('..'))
Then I added one of the scripts in my package to index.rst to see how Sphinx works.
.. toctree::
:maxdepth: 2
:caption: Contents:
mypackage/moprob
The error code I get:
.../index.rst:9: WARNING: toctree contains reference to nonexisting document u'mypackage/moprob'
Solutions I have tried:
Adding sphinx.ext.napoleon to the extensions list since all of my doc strings are written using the NumPy format. The error did not go away. I also put the napoleon extension after autodoc because one of the documentation pages suggested that.
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.napoleon']
Adding numpydoc_show_class_members = False to conf.py. I put this directly below the extensions but it also did not solve the error.
A couple of different configurations for folder locations. I've also tried setting the root location to be /myfolder and setting the source to be /mypackage and the build to be /doc. None has worked.
The toctree directive contains references to reStructuredText documents, not Python scripts or modules. Sphinx expects there to be a mypackage/moprob.rst file (in the doc folder), but there isn't one. Hence the error.
To quickly get some meaningful output, create the mypackage/moprob.rst file. Add a heading and an automodule directive in it:
moprob module
=============
.. automodule:: mypackage.moprob
:members:
Then run sphinx-build again.