In the documentation about sphinx extensions are some "config values". e.g. in sphinx.ext.autodoc.
But I do not know how to set these values. Is it a parameter on the shell I have to set?
There's a page on the docs that teaches how to use extensions. The page is here: https://www.sphinx-doc.org/en/master/usage/extensions/index.html
In this page you have the following description:
A list of strings that are module names of extensions. These can be extensions coming with Sphinx (named sphinx.ext.*) or custom ones.
This tells you that sphinx.ext.* are the built-ins extensions (You can confirm that from here)
Basically when it states some kind of configuration, it refers to the conf.py file that is generated when you run sphinx-quickstart, which is a quick-setup command for sphinx in general (Might be a good read: https://www.sphinx-doc.org/en/master/usage/quickstart.html)
The root directory of a Sphinx collection of plain-text document sources is called the source directory. This directory also contains the Sphinx configuration file conf.py, where you can configure all aspects of how Sphinx reads your sources and builds your documentation.
Sphinx comes with a script called sphinx-quickstart that sets up a source directory and creates a default conf.py with the most useful configuration values from a few questions it asks you.
Note that, as it's built-in, it's already setupped with your sphinx project.
But if you want to customize it somehow, you can use conf.py file with autodoc_* configurations (As listed here)
There are also some notes that might be useful for your case
For Sphinx (actually, the Python interpreter that executes Sphinx) to find your module, it must be importable. That means that the module or the package must be in one of the directories on sys.path – adapt your sys.path in the configuration file accordingly.
Related
I have a python package built from source code in /Document/pythonpackage directory
/Document/pythonpackage/> python setup.py install
This creates a folder in site-packages directory of python
import pythonpackage
print(pythonpackage.__file__)
>/anaconda3/lib/python3.7/site-packages/pythonpackage-x86_64.egg/pythonpackage/__init__.py
I am running a script on multiple environments so the only path I know I will have is pythonpackage.__file__. However Document/pythonpackage has some data that is not in site-packages is there a way to automatically find the path to /Document/pythonpackage given that you only have access to the module in python?
working like that is discouraged. it's generally assumed that after installing a package the user can remove the installation directory (as most automated package managers would do). instead you'd make sure your setup.py copied any data files over into the relevant places, and then your code would pick them up from there.
assuming you're using the standard setuptools, you can see the docs on Including Data Files, which says at the bottom:
In summary, the three options allow you to:
include_package_data
Accept all data files and directories matched by MANIFEST.in.
package_data
Specify additional patterns to match files that may or may not be matched by MANIFEST.in or found in source control.
exclude_package_data
Specify patterns for data files and directories that should not be included when a package is installed, even if they would otherwise have been included due to the use of the preceding options.
and then says:
Typically, existing programs manipulate a package’s __file__ attribute in order to find the location of data files. However, this manipulation isn’t compatible with PEP 302-based import hooks, including importing from zip files and Python Eggs. It is strongly recommended that, if you are using data files, you should use the ResourceManager API of pkg_resources to access them
Not sure, but you could create a repository for your module and use pip to install it. The egg folder would then have a file called PKG-INFO which would contain the url to the repository you imported your module from.
I’ve got a problem visualizing the documentation of my project in Read the Docs. Everything works fine locally by executing the command make html, but in Read the Docs the functions that should be generated by the directive automodule don’t show up.
This is how my repository is structured.
In the conf.py I set the absolute path as follows: sys.path.insert(0, os.path.abspath('../..')), and then I used the following instruction for automatically describing the functions contained in the Python module in my documentation:
.. automodule:: library.module1
:members:
However, no functions are shown by compiling the doc in Read The Docs.
I also tried to install my project in a virtualenv by specifying a requirements.txt file in the RTD advanced settings, but this doesn’t work either. Any suggestions?
The setuptools documentation is very explicit about adding code to __init__.py files from namespaces:
You must NOT include any other code and data in a namespace package's __init__.py. Even though it may appear to work during development, or when projects are installed as .egg files, it will not work when the projects are installed using "system" packaging tools -- in such cases the __init__.py files will not be installed, let alone executed.
Yet, I do not understand what these "system" packaging tools are. What are they? How could I reproduce this situation where the __init__.py files are gone?
#Anzel's comment looked like a good answer, and I'd say PEP-420 confirms that. In its Rationale section, we read:
Namespace packages are designed to support being split across multiple directories (and hence found via multiple sys.path entries). In this configuration, it doesn't matter if multiple portions all provide an __init__.py file, so long as each portion correctly initializes the namespace package. However, Linux distribution vendors (amongst others) prefer to combine the separate portions and install them all into the same file system directory. This creates a potential for conflict, as the portions are now attempting to provide the same file on the target system - something that is not allowed by many package managers. Allowing implicit namespace packages means that the requirement to provide an __init__.py file can be dropped completely, and affected portions can be installed into a common directory or split across multiple directories as distributions see fit.
So yes, we cannot add any more code to our __init__.py files because OS package managers (and others) would prefer to merge them into only one directory tree.
I typically use certain extensions such as sphinxcontrib.bibtex with every Sphinx documentation project, which means I need to add the extension to the conf.py file for each project.
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest',
'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage',
'sphinx.ext.pngmath', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode',
'sphinxcontrib.bibtex']
Is there a simple what of including these by default in conf.py?
You could create a module containing your default settings, and then import them into your configuration file.
However, unless you are working on the project alone, it's probably better to always include the full configuration in a project so that other people working on it know they are building it with the same settings.
Another alternative might be to create a template configuration file with those settings that you could use for new projects.
I want to generate documentation for my package. Every file in the project contains extensive documentation. Is there a way to quickly add my entire project to the documetation index?
I'd like to automatically generate some documentation for the entire project with as little as possible work. I started by adding the following to index.rst:
.. automodule:: mymodulename
:members:
All that seems to have done is document elenments in the __init__.py file (just a docstring) - is there any way I can make it document everything else? I'm looking to add absolutely everything defined in my package and have every single class, constant, function (etc) in the package be added to the appropriate index.
Can this be done?
You can use sphinx-apidoc.
From the official documentation: sphinx-apidoc is a tool for automatic generation of Sphinx sources that, using the autodoc extension, document a whole package in the style of other automatic API documentation tools.
An usage example could be (from your project root directory):
$ sphinx-apidoc . --full -o doc -H 'MyProject' -A 'MyName' -V '1.0'
A doc directory would be created with everything ready inside.
You can also adjust the settings of your documentation editing the auto-generated conf.py file.
Other useful information can be found in similar question posted here.