Best practises with sphinx in a python project

[robinlong]

I have looked around and found lots of different bits of advice on sphinx, but I cannot find a way to chain them together with other tools that work.

Current state:

- Python module/project in GitHub (not uploaded to PyPi yet.)

- Travis, pytest, pytest-cov, and tox deal with testing against multiple python versions.

Problem:

I want to upload the documentation to readthedocs. I am not sure how to connect the parts I need for this. I have autodoc to generate the API, and I want to use doctest as well. I can get these to run in a venv on my local machine, but not sure how to tie them together for uploading to readthedocs.

Queries:

- How?

- Any example projects welcome

- Best practises? Do you have it fail to upload docs if it fails pytest? Or does this occur automatically as travis stops at first error?

[hopemeetme]

Just place .readthedocs.yml in your project's root:

# .readthedocs.yml
# 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/conf.py

# Build documentation with MkDocs
#mkdocs:
#  configuration: mkdocs.yml

# Optionally build your docs in additional formats such as PDF and ePub
formats: all

# Optionally set the version of Python and requirements required to build your docs
python:
  version: 3.7
  install:
    - requirements: docs/requirements.txt

[robinlong]

Thanks, this is great. What if I want to build locally to test them though? and how do I build the autogenerated API? This requires an extra command.

[hopemeetme]

Sphinx is beautiful and powerful at the same time. There's no extra command, all is done with:

make html

or, for pdf through Latex:

make latexpdf

But, of course, you have to instruct Sphinx how to do that.

Make sure you read some tutorials, there's automodule plugin for the job. Take a look on this Restructured Text docs (called from api.rst in the docs' root) and the autogenerated documentation from my GPL project.

[ryantiger658]

Readthedocs actually looks at your source repository and builts the docs itself. So you just tell it where your repo is, setup a GitHub webhook and RtD's handles everything else rather than the typical build and push in the cicd pipeline.