I am very new to Sphinx. Doc says it is easy to set up - maybe so but I am having a bear of a time. I finally have .rst files being created but while I have updated index.rst I am getting this error. I confirmed the .rst files exist in the /docs directory. Below are the syspath from my conf.py and the index.
I have tried all of these combinations without success - the .rst files reside in /home/efultz/src/Sicom2.0/docs
sys.path.insert(0, os.path.abspath('/home/efultz/src/Sicom2.0/'))
sys.path.insert(0, os.path.abspath('/home/efultz/src/Sicom2.0/docs'))
sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath('../'))
sys.path.insert(0, os.path.abspath('../..'))
sys.path.insert(0, '/home/efultz/src/Sicom2.0/')
I have the following in the index.rst - I have confirmed there are only 3 spaces before the individual filenames
.. toctree::
:maxdepth: 2
:caption: Contents:
Base
BaseAPI
EventLogger
SICOMToConnex
SICOMToConnexAPI
SICOMToConnexAPIProduct
SICOMToConnexDemo
SICOMToConnexParser
SICOMToConnexParserAPI
SICOMToConnexParserAPIProduct
product
modules
I found by configuring to use the same directory instead of splitting directories when the .RST files were created they were where they needed to be.
Related
My latest Sphinx documentaion fails when trying to build it with readthedocs. It has apperently something to do with the fact that I am trying to incorporate some badges from https://shields.io/. These badges are .svg graphic files.
I probably need to do some tweaking in my conf.py file?
On my local machine, I am able to produce the Sphinx documentation and all HTML files do look OK.
Here's an excerpt of my conf.py file:
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
"nbsphinx",
"numpydoc",
"sphinx.ext.autodoc",
"sphinx_copybutton",
"sphinx.ext.napoleon",
]
napoleon_google_docstring = False
napoleon_numpy_docstring = True
numpy_validation_checks = {all}
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = "sphinx_rtd_theme"
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = []
Here's the text output: https://readthedocs.org/api/v2/build/17082650.txt
Although you may have disabled the epub and PDF builds in the RTD UI, you must take note in the RTD UI under Advanced Settings > Default settings:
These settings can be configured using a configuration file. That's the recommended way to set up your project. Settings listed here are ignored when using a configuration file.
Therefore you must be using a configuration file that enables both pdf and epub builds. Lo and behold:
https://github.com/andreas-vester/df2img/blame/3ba6e046c8d30ab3896b23835513740bd5aa97fa/.readthedocs.yaml#L12-L14
formats:
- pdf
- epub
In my docs/source/conf.py I have this code:
extensions = [
"sphinx.ext.autodoc",
"myst_parser",
]
source_suffix = ['.rst', '.md']
All my files are in Markdown, not in reStructuredText.
On ReadTheDocs, the initial build was successful technically, only until the modules page was "not found" and the index page is completely blank.
My .readthedocs.yaml:
# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/source/conf.py
# Optionally build your docs in additional formats such as PDF
formats: all
# Optionally set the version of Python and requirements required to build your docs
python:
version: "3.8"
install:
- method: pip
path: .
extra_requirements:
- docs
My setup.cfg contains this:
[options.extras_require]
docs =
sphinx
myst-parser
Of course, doing make clean html in docs/ works completely fine. Not sure why ReadTheDocs cannot properly link to the rest of the.md files from index.md.
I solved it. I checked the build logs, turns out I have some syntax errors (I did list[str] not List[str] with from typing import List)
I have followed the getting started guide on Readthedocs and have used Sphinx using autodoc to create the documentation for my Python package on https://github.com/akdiem/bloodflow. (documentation relevant .rst files are in the docs folder)
The readthedoc build passed and is found on https://bloodflow.readthedocs.io/en/latest/
Readthedocs does not show any of the docstring documentation that is part of my code, but to me everything looks like it should. Why does it not?
Autodoc is a Sphinx extension that looks at its automodule directive references in .rst files during build time, imports and identifies Python code and then converts their docstrings into html.
Since your module is not installed into the environment with a setup.py,
It needs to import your module manually so you need to give sphinx context in conf.py:
import os
import sys
#Location of Sphinx files
sys.path.insert(0, os.path.abspath('./../..'))
In this case, the absolute path to your top module is 2 levels above the conf.py file.
After this you can add your autodoc directive file arteryfe.rst back to index.rst toctrees and it should be showing up.
Welcome to artery.fe's documentation!
=====================================
.. toctree::
:maxdepth: 2
:caption: Contents:
arteryfe
getting_started
tutorial
theory
numerical
In the case you ever want to make an environment installation, you'll have to tick the option for ReadTheDocs to use a virtualenvironment and utilize site-packages.
Addendum:
This is another way to do it and is particularly useful if you have more than one package.
Manually creating files with Autodoc directives can be problematic in larger codebases, so we have Sphinx Apidoc - it is an extension complementing the Autodoc extension.
This means that you may run sphinx-apidoc with the preferred options and it will generate .rst files from your Docstrings with the automodule directives - which will then generate into html. However this can also be done through conf.py during build time in RTD.
For instance, this would have Sphinx generate an automodule arteryfe.rst file in /source/_autogen during build time:
import os
import sys
#Location of Sphinx files
sys.path.insert(0, os.path.abspath('./../..'))
import sphinx.apidoc
def setup(app):
sphinx.apidoc.main(['-f', #Overwrite existing files
'-T', #Create table of contents
#'-e', #Give modules their own pages
'-E', #user docstring headers
#'-M', #Modules first
'-o', #Output the files to:
'./source/_autogen/', #Output Directory
'./../arteryfe', #Main Module directory
]
)
After that just glob all the autogen output into your toctree.
Welcome to artery.fe's documentation!
=====================================
.. toctree::
:maxdepth: 2
:caption: Contents:
getting_started
tutorial
theory
numerical
.. toctree::
:maxdepth: 2
:glob:
:caption: Code:
_autogen/*
It a bit less flexible since making templates for apidoc is complicated. It is still a valid solution and useful in some cases (i.e. huge codebases).
I've scribbled an RTD compatible Example here for apidoc multipackages.
I have troubles creating a document directory (html) using sphinx-build.
I tried
sphinx-build -b html source build
as well as
make html
but in both cases only the html-files search.html, index.html and genindex.html are generated. The file modindex.html is missing.
In the file conf.py I set
html_domain_indices = True
so I should have a modindex.html file. What am I doing wrong? I get no error message after building the html files. I'm using Sphinx 1.1.3 and Python 2.7 on Windows XP.
Short version
run sphinx-apidoc -o . mymodule
uncomment and modify conf.py. For this example, sys.path.insert(0, os.path.abspath('mymodule'))
re-run make html
Long answer
I can reproduce the issue with this sample module:
$cat mymodule/mymodule.py
def fn1():
'''First function'''
pass
def fn2():
'''Second function'''
pass
Running sphinx-quickstart produces the following tree:
$tree
.
├── Makefile
├── _build
├── _static
├── _templates
├── conf.py
├── index.rst
├── mymodule
└── mymodule.py
$cat index.rst
.. sphinx example documentation master file, created by
sphinx-quickstart on Mon Mar 30 15:28:37 2015.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
with default index.rst:
Welcome to sphinx example's documentation!
==========================================
Contents:
.. toctree::
:maxdepth: 2
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Running make html at this point produces no output in _build/html/py-modindex.html. This is because sphinx needs .rst files describing every module. Fortunately it's easy to produce using sphinx-apidoc -o . mymodule.
This gives two new files, of which only mymodule.rst is necessary to fix the modindex issue in the question.
$head *mod*rst
==> modules.rst <==
mymodule
========
.. toctree::
:maxdepth: 4
mymodule
==> mymodule.rst <==
mymodule module
===============
.. automodule:: mymodule
:members:
:undoc-members:
:show-inheritance:
Running make html at this point still won't work. But uncommenting and changing the line beginning with sys.path.insert in conf.py fixes things.
Mine is: sys.path.insert(0, os.path.abspath('mymodule'))
PS: to avoid an additional warning, add modules to the Contents: toctree in the index.rst file.
The following is what I did for my project.
1. Install sphinx
pip install -U sphinx
2. Install theme (I've chosen sphinx_rtd_theme. Pleaser replace it with your choice)
pip install sphinx sphinx_rtd_theme
3. Create a doc directory under your project file
mkdir docs
4. Get into that directory
cd docs
5. Run sphinx-quickstart command
sphinx-quickstart
6. Run the following ( if you've enabled autodoc shpinx extension)
sphinx-apidoc -o source/ ../<modules_folder>
where source is the source folder used by sphinx and modules_folder is the folder your project's .py files-modules are in.
7. You will be prompted to reply to the questions below (change the answers according to your needs)
> Separate source and build directories (y/n) [n]: y
The project name will occur in several places in the built documentation.
> Project name: project_name
> Author name(s): your_nme
> Project release []: 1.01
> Project language [en]: en
8. It should look like the following if successfully run:
Creating file ...<***modules_folder***>/docs/source/conf.py.
Creating file ...<***modules_folder***>/docs/source/index.rst.
Creating file ...<***modules_folder***>/docs/Makefile.
Creating file ...<***modules_folder***>/docs/make.bat.
Finished: An initial directory structure has been created.
9. Edit conf.py and make sure the following lines are not commented (#):
import os # line 13
import sys # line 14
Note: .. stands for one directory up from doc directory
<modules_folder> is the folder your project's .py files-modules are in
sys.path.insert(0, os.path.abspath('../<modules_folder>/')) # line 16
make sure the following line exists
extensions = ['sphinx.ext.autodoc'] # line 34
change the theme if you'd like
html_theme = 'sphinx_rtd_theme' # line 51
10. Run shpinx-apidoc command
sphinx-apidoc -o . ..
Note:
. >> is for current directory
..>> is for one level up directory, i.e., the <modules_folder> project directory
11. Run make html command
.\make clean
.\make HTML
or
make clean
make html
12. Open your newely built webpage starting with
<modules_folder>/docs/build/html/index.html
Old question, but "working on the hard drive but not on ReadTheDocs" often has an easy fix.
Go to readthedocs
Navigate to your "Project Home"
Click 'Admin' then 'Advanced Settings'
Find and check the box for 'Install Project'
Return to 'Overview'
Build a new version
Check if it worked
Come back here and thank me
I've setup a custom configuration file for Pylint (name, conveniently, config). There has to be a way that I don't have to include --rcfile=config on every run. How can I set the config file permanently?
When you do not specify the --rcfile option, Pylint searches for a configuration file in the following order and uses the first one it finds:
pylintrc in the current working directory
If the current working directory is in a Python module, Pylint
searches up the hierarchy of Python modules until it finds a
pylintrc file. This allows you to specify coding standards on a
module-by-module basis. Of course, a directory is judged to be a
Python module if it contains an __init__.py file.
The file named by environment variable PYLINTRC
.pylintrc in your home directory, unless you have no home directory
or your home directory is /root
.pylintrc in the current working directory
/etc/pylintrc
Thus depending on the method you choose, Pylint can use a different configuration file based on the location of the code, the user or the machine.
Note that the configuration file only applies to Python files that are in modules. Thus, Pylint still uses its default rules when analyzing Python files in a directory with no __init__.py file.
For example, I have a bin/ directory containing command line applications. Ordinarily, this directory needs no __init__.py file because it is never imported. I had to add a bin/__init__.py file to get Pylint to analyze these Python files using my pylintrc file.
set the path to that file in the PYLINTRC environment variable, or rename the file $HOME/.pylintrc or /etc/pylintrc (the latter is probably only supported on *nix)
It can be done using .pre-commit-config.yaml. This snippet below need to be added to .pre-commit-config.yaml:
repos:
- repo: local
hooks:
- id: pylint
name: pylint
entry: pylint
language: system
types: [python]
args: [
"-rn", # Only display messages
"-sn", # Don't display the score
"--rcfile=.pylintrc", # Link to your config file
"--load-plugins=pylint.extensions.docparams", # Load an extension
]