I am playing around with Sphinx 4.4.0 in a test project. I use sphinx.ext.autodoc and sphinx-apidoc.
But not all py files are recognized. It seams like that files with a starting _ in filename are ignored (e.g. _mypackage.py). But i am not sure if that character is the cause or something else.
Are you aware of an option to modify that behavior?
This is the project structure
sphinx_versuch
├── docs
│ ├── make.bat
│ ├── Makefile
│ └── source
│ ├── conf.py
│ ├── index.rst
│ ├── modules.rst
│ ├── mypackage.rst
│ ├── _static
│ └── _templates
├── LICENSE
├── README.md
├── src
│ ├── mypackage
│ │ ├── a.py
│ │ ├── b.py
│ │ ├── __init__.py
│ │ └── _mypackage.py
│ ├── setup.cfg
│ └── setup.py
└── tests
├── __init__.py
├── test_a.py
├── test_b.py
└── test_mypackage.py
The option --private or -P for sphinx-apidoc make sure that private files (which start with an underscore by convention) are included also.
See also
https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html#cmdoption-sphinx-apidoc-P
Related
I'm trying to run my tests using python -m pytest but I get an error that
ModuleNotFoundError: No module named 'sample'
When using nosetests or anything else it works fine, but when trying to use pytest, it doesn't work.
My tree looks like below, do you have any advice why it doesn't work?
├── LICENSE.txt
├── README.md
├── data
│ └── data_file
├── exported_register.csv
├── pyproject.toml
├── requirements.txt
├── setup.cfg
├── setup.py
├── src
│ └── sample
│ ├── __init__.py
│ ├── __pycache__
│ │ ├── __init__.cpython-39.pyc
│ │ ├── dziennik.cpython-39.pyc
│ │ ├── przedmiot.cpython-39.pyc
│ │ ├── simple.cpython-39.pyc
│ │ └── uczen.cpython-39.pyc
│ ├── dziennik.py
│ ├── package_data.dat
│ ├── przedmiot.py
│ ├── simple.py
│ └── uczen.py
├── tests
│ ├── __init__.py
│ ├── __pycache__
│ │ ├── __init__.cpython-39.pyc
│ │ ├── test_ASSERTPY_uczen.cpython-39-pytest-6.2.1.pyc
│ │ ├── test_ASSERTPY_uczen.cpython-39-pytest-6.2.5.pyc
│ │ ├── test_ASSERTPY_uczen.cpython-39.pyc
│ │ ├── test_PYHAMCREST_uczen.cpython-39-pytest-6.2.1.pyc
│ │ ├── test_PYHAMCREST_uczen.cpython-39-pytest-6.2.5.pyc
│ │ ├── test_PYHAMCREST_uczen.cpython-39.pyc
│ │ ├── test_UNITTEST_register.cpython-39-pytest-6.2.1.pyc
│ │ ├── test_UNITTEST_register.cpython-39-pytest-6.2.5.pyc
│ │ ├── test_UNITTEST_register.cpython-39.pyc
│ │ ├── test_UNITTEST_uczen.cpython-39-pytest-6.2.1.pyc
│ │ ├── test_UNITTEST_uczen.cpython-39-pytest-6.2.5.pyc
│ │ ├── test_UNITTEST_uczen.cpython-39.pyc
│ │ ├── test_simple.cpython-39-pytest-6.2.1.pyc
│ │ ├── test_simple.cpython-39-pytest-6.2.5.pyc
│ │ └── test_simple.cpython-39.pyc
│ ├── test_ASSERTPY_uczen.py
│ ├── test_PYHAMCREST_uczen.py
│ ├── test_UNITTEST_register.py
│ ├── test_UNITTEST_uczen.py
│ └── test_simple.py
└── tox.ini
When you run pytest with python -m pytest it uses the current directory as it its working dir, which doesn't contain the sample module (located inside ./src). The way I deal with this is I have a conftest.py inside my tests directory where I add my source dir to python path something like this:
import sys
from pathlib import Path
source_path = Path(__file__).parents[1].joinpath("src").resolve()
sys.path.append(str(source_path))
I've recently started using pytorch and have had similar problems. Couple steps come to mind:
How are you writing the .py file that contains the tests? It may simply be that you need to change up how you import sample within the unit test file. I would expect that you need something like import src.sample.simple. In other words, could be just a pathing issue.
Try a (much) simpler folder structure and try again. If that doesn't work, try to just copy an example of a simple scheme that someone has posted. That is, just get python -m pytest to run somehow, then start slowly adding the complexities of your project.
I'm trying to generate documentation for my library. Since the library directory structure is quite big, I want Sphinx to generate the .rst files as a nested directory that mirrors the package and module structure.
The library structure:
pyflocker/
├── __init__.py
├── ciphers/
│ ├── __init__.py
│ ├── backends/
│ │ ├── __init__.py
│ │ ├── _asymmetric.py
│ │ ├── _symmetric.py
│ │ ├── cryptodome_/
│ │ │ ├── AES.py
│ │ │ ├── ChaCha20.py
│ │ │ ├── ECC.py
│ │ │ ├── Hash.py
│ │ │ ├── RSA.py
│ │ │ ├── __init__.py
│ │ │ ├── _serialization.py
│ │ │ └── _symmetric.py
│ │ └── cryptography_/
│ │ ├── AES.py
│ │ ├── Camellia.py
│ │ ├── ChaCha20.py
│ │ ├── DH.py
│ │ ├── ECC.py
│ │ ├── Hash.py
│ │ ├── RSA.py
│ │ ├── __init__.py
│ │ ├── _serialization.py
│ │ └── _symmetric.py
│ ├── base.py
│ ├── exc.py
│ ├── interfaces/
│ │ ├── AES.py
│ │ ├── Camellia.py
│ │ ├── ChaCha20.py
│ │ ├── DH.py
│ │ ├── ECC.py
│ │ ├── Hash.py
│ │ ├── RSA.py
│ │ └── __init__.py
│ └── modes.py
└── locker.py
Till now I was using sphinx-apidoc -e -o ... to generate the documentation within the docs/source/ folder.
But this doesn't work as expected.
Expected Results:
Documentation generated as a nested directory. The files have been removed to keep the backbone only.
docs/source/
└── ciphers/
└── backends/
├── cryptodome_/
└── cryptography_/
Actual results:
The whole module name is retained.
docs/source/
├── ... # skipping boilerplate files
├── pyflocker.ciphers.backends.cryptodome_.AES.rst
├── pyflocker.ciphers.backends.cryptodome_.ChaCha20.rst
├── pyflocker.ciphers.backends.cryptodome_.ECC.rst
├── pyflocker.ciphers.backends.cryptodome_.Hash.rst
├── pyflocker.ciphers.backends.cryptodome_.RSA.rst
├── pyflocker.ciphers.backends.cryptodome_.rst
├── pyflocker.ciphers.backends.cryptography_.AES.rst
├── pyflocker.ciphers.backends.cryptography_.Camellia.rst
├── pyflocker.ciphers.backends.cryptography_.ChaCha20.rst
├── pyflocker.ciphers.backends.cryptography_.DH.rst
├── pyflocker.ciphers.backends.cryptography_.ECC.rst
├── pyflocker.ciphers.backends.cryptography_.Hash.rst
├── pyflocker.ciphers.backends.cryptography_.RSA.rst
├── pyflocker.ciphers.backends.cryptography_.rst
├── pyflocker.ciphers.backends.rst
├── pyflocker.ciphers.base.rst
├── pyflocker.ciphers.exc.rst
├── pyflocker.ciphers.interfaces.AES.rst
├── pyflocker.ciphers.interfaces.Camellia.rst
├── pyflocker.ciphers.interfaces.ChaCha20.rst
├── pyflocker.ciphers.interfaces.DH.rst
├── pyflocker.ciphers.interfaces.ECC.rst
├── pyflocker.ciphers.interfaces.Hash.rst
├── pyflocker.ciphers.interfaces.RSA.rst
├── pyflocker.ciphers.interfaces.rst
├── pyflocker.ciphers.modes.rst
├── pyflocker.ciphers.rst
├── pyflocker.locker.rst
└── pyflocker.rst
Is there any way to generate the doc as a directory tree?
What you specify isn't currently possible.
sphinx-apidoc will not create directories mirroring your package/file structure.
sphinx-apidoc will not distribute .rst files along several directories mirroring your package/file structure.
Notice the sphinx-apidoc signature, you can specify one input path for modules, and one output path for the .rst files:
Synopsis
sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN …]
You'll have to write your own script to recurse into your file system and execute sphinx-apidoc once for every package/directory with <MODULE_PATH> mirroring <OUTPUT_PATH>.
This may seem counter-intuitive, however the Python philosophy is:
The Zen of Python - PEP 20
Flat is better than nested.
Arguably it is more convenient to have sphinx-apidoc produce the .rst files with dotted names mirroring the package/module structure, because you get an overview of the packages at a glance and it tends to save clicking.
If you want to organize some .rst files into directories afterwards it is possible to link them, at the time of this writing it is however not possible to generate such a tree automatically using sphinx-apidoc in a single execution.
It is possible to do so using sphinx-nested-apidoc.
It mirrors the original package structure and generates appropriate files.
Note that it does not edit the files or the links within it. It just renames or moves them.
My python project installs via setup.py. The project structure looks like:
├── Makefile
├── README.rst
├── circle.yml
├── docs
│ ├── Makefile
│ ├── conf.py
│ ├── deps.txt
│ ├── guide_installation.rst
│ ├── guide_model.rst
│ ├── guide_transliteration.rst
│ ├── index.rst
│ ├── make.bat
│ └── module_trans.rst
├── indictrans
│ ├── __init__.py
│ ├── _decode
│ ├── _utils
│ ├── base.py
│ ├── iso_code_transformer.py
│ ├── libindic_
│ ├── mappings
│ ├── models
│ ├── polyglot_tokenizer
│ ├── script_transliterate.py
│ ├── test.py
│ ├── tests
│ ├── transliterator.py
│ ├── trunk
│ └── unicode_marks.py
├── requirements.txt
├── setup.cfg
├── setup.py
├── test-requirements.txt
└── tox.ini
where the subfolder indictrans/models looks like
├── ben-eng
│ ├── classes.npy
│ ├── coef.npy
│ ├── intercept_final.npy
│ ├── intercept_init.npy
│ ├── intercept_trans.npy
│ └── sparse.vec
├── ben-guj
│ ├── classes.npy
│ ├── coef.npy
│ ├── intercept_final.npy
│ ├── intercept_init.npy
│ ├── intercept_trans.npy
│ └── sparse.vec
so I have .npy and .vec files to be included in the project.
In my setup.py I'm trying to explicitly include this folder models via the include_package_data directive like:
setup(
setup_requires=['pbr'],
pbr=True,
packages=find_packages(),
include_package_data=True,
package_data={'models': ['*.npy','*.vec']},
ext_modules=cythonize(extensions)
)
and in the setup.cfg I have
[files]
packages =
indictrans
but running python setup.py install does not copy the models folder to the installation folder /usr/local/lib/python2.7/dist-packages/indictrans/.
If I print the it is the output of the find_packages I get
['indictrans', 'indictrans.tests', 'indictrans.libindic_', 'indictrans._utils', 'indictrans._decode', 'indictrans.polyglot_tokenizer', 'indictrans.models', 'indictrans.trunk', 'indictrans.libindic_.utils', 'indictrans.libindic_.soundex', 'indictrans.libindic_.utils.tests', 'indictrans.libindic_.soundex.utils', 'indictrans.libindic_.soundex.tests', 'indictrans.libindic_.soundex.utils.tests', 'indictrans.polyglot_tokenizer.tests', 'indictrans.trunk.tests']
so I will assume that indictrans/models would be included, but it is not.
Add include_package_data=True to your setup-function (you already did that).
Create a file MANIFEST.in in the same directory as setup.py
MANIFEST.in can look as follows:
include indictrans/models/ben-eng/*
include indictrans/models/ben-guj/*
You don't need setup.cfg for doing this.
Source: This great writeup of python packaging
EDIT about recursive-include:
According to the documentation this should also work:
recursive-include indictrans/models *.npy *.vec
include_package_data=True requires MANIFEST.in.
To include data for the module indictrans.models you have to provide the full name:
package_data={'indictrans.models': ['*.npy','*.vec']},
I've got a directory structure like:
Folder_in_PYTHONPATH/
├── Package1
│ ├── __init__.py
│ ├── src
│ │ ├── Class1.py
│ │ ├── Class2.py
│ │ └── __init__.py
│ └── test
│ └── testfile.py
├── Package2
│ ├── __init__.py
│ ├── src
│ │ ├── Class1.py
│ │ ├── Class2.py
│ │ └── __init__.py
│ └── test
│ ├── test1.py
│ └── test2.py
.
.
.
When I import things from this folder, I need to always type
import Package1.src.Class1
Is there any way to set up my __init__.py so that I can just type
import Package1.Class1
instead?
Add them into your packages' __init__.py files so they look like:
from src import Class1
from src import Class2
Have a look at the docs
I would recommend putting the *.py files in the top level folder of their package to get the import Package_1.Class1 behaviour you are after. The unit tests can stay in their own folder to keep them separate.
When I run an import in my development environment, I seem to get the wrong module.
How do I make sense of this?
$ python -c "import breathe.renderer.rst.doxygen.compound as com; print com"
<module 'breathe.parser.doxygen.compound' from 'breathe/parser/doxygen/compound.pyc'>
The layout of the breathe directory is:
breathe
├── directives.py
├── finder
│ ├── doxygen
│ │ ├── base.py
│ │ ├── compound.py
│ │ ├── index.py
│ │ └── __init__.py
│ └── __init__.py
├── __init__.py
├── nodes.py
├── parser
│ ├── doxygen
│ │ ├── compound.py
│ │ ├── compoundsuper.py
│ │ ├── index.py
│ │ ├── indexsuper.py
│ │ ├── __init__.py
│ ├── __init__.py
├── process.py
├── renderer
│ ├── __init__.py
│ └── rst
│ ├── doxygen
│ │ ├── base.py
│ │ ├── compound.py
│ │ ├── domain.py
│ │ ├── filter.py
│ │ ├── index.py
│ │ ├── __init__.py
│ │ └── target.py
│ ├── __init__.py
└── transforms.py
Check your breathe/renderer/rst/__init__.py file. I suspect that you have something like
from breathe.parser import doxygen
What happens is that when a module is imported, the module's __init__.py is executed. Then the next submodule is imported and it's __init__.py is run.
So, in the above situation, you'll get breathe.renderer.rst importing fine, but when running
breathe.renderer.rst.__init__, the breathe.parser.doxygen module is bound to the local name doxygen overriding the doxygen submodule. So you should see something like this:
>>> from breathe.renderer import rst
>>> print(rst.doxygen)
<module 'breathe.parser.doxygen' from 'breathe/parser/doxygen/__init__.pyc'>
Possible solutions:
Use absolute imports in __init__.py
Keep as much code as possible out of __init__.py
Use import inside the functions it's needed rather than globally. (This can also resolve circular import problems)
Note that there is nothing that prohibits code in __init__.py, and several modules in the stdlib do it too. However, because of exactly this sort of issue it is generally considered a good idea to avoid doing it too much.