Build infrastructure for Read the Docs
Project description
This module is the main building interface to Read the Docs. It has no explicit dependency on RTD code itself, and can be used outside of RTD to test your builds.
Install
Install with pip:
pip install readthedocs-build
CLI Use
Running a build is simple:
rtd-build
This will search for all readthedocs.yml (or .readthedocs.yml) files below your current directory and will build your documentation.
You can set a specific a directory where the built documentation should be stored:
rtd-build --outdir=out_dir
The documentation will then be placed in out_dir/<name>/html/. Where <name> is the name configured in your readthedocs.yml. The default for --outdir is _readthedocs_build.
Run rtd-build –help for more information.
The Build
Here is a list of steps that rtd-build performs to built your documentation. All these steps are performed for each individual section in your readthedocs.yml configs.
it creates a new virtual environment with virtualenv
it installs the builder’s dependencies into the virtualenv, for example Sphinx
it runs the build command (e.g. sphinx-build) on your documentation and puts the output into the directory specified with --outdir.
it removes the virtualenv
Library Use
An example use of this library is:
import os
from readthedocs_build.build import build
build([{
'output_base': os.path.abspath('outdir'),
'name': 'docs',
'type': 'sphinx',
'base': os.path.dirname(os.path.abspath(__file__)),
}])
Development
Just run:
pip install -e .
This will install the project into your environment, and have it pick up changes as you edit them in the code.
To run the tests:
tox
Build Process
Read the Docs creates a full environment for your build. In your local environment, you can choose what portions of this environment to re-create. You can either use your existing environment with our builder code installed, or allow our builder to create a fully isolated environment for itself. A fully isolated environment is much closer to our production build environment for testing purposes.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for readthedocs_build-2.0.7-py2-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7cab6d4e9e92e51628832786484191d12b36d576b929138b494a638b536c76a4 |
|
MD5 | aeff1f7f14f9fc9bdd339acdb1fcfffe |
|
BLAKE2b-256 | 2383a6c4c4b7942bc16737f2cf94571a254cfa0905f66527d38d936d10312ea1 |