A hack to run custom shell commands when building documentation on Read the Docs.

Related tags

Documentation python readthedocs
Overview

readthedocs-custom-steps

A hack to run custom steps when building documentation on Read the Docs.

Important: This module should not be installed outside of a Read the Docs build environment. It will rename your Python executable and install a substitute. It does not currently provide an automated way to revert this change.

How to use this?

Rtd-cs overrides your python installation with a Bash script that dispatches the execution of custom steps upon invokation of python -m mkdocs or python -m sphinx. The commands to run are defined in a file called .readthedocs-custom-steps.yml.

Example:

# .readthedocs-custom-steps.yml
steps:
- bash .scripts/generate-changelog.sh >docs/changelog.md
- python -m "$@"

Here, $@ contains the arguments after python -m in the Read the Docs build step, for example:

  • mkdocs build --clean --site-dir _site/html --config-file mkdocs.yml
  • sphinx -T -b html -d _build/doctrees -D language=en . _build/html

An infinite recursion of this script invoking itself in the example above is prevented automatically with the RTD_CUSTOM_ENTRY environment variable.

Configuration

The file containing the steps must be a YAML file called .readthedocs-custom-steps.yml. It is searched for in the following locations:

  1. .readthedocs-custom-steps.yml
  2. docs/.readthedocs-custom-steps.yml
  3. Relative to any directories from which requirements files are specified in the .readthedocs.yml file under the $.python.install[*].requirements configuration option.

Environment

In addition to passing the original arguments to the custom steps, Rtd-cs provides PYTHON environment variables as detected from the ~/.pyenv/shims folder in the RTD build environment. (e.g. if there is a shim python3.6 and python3.7, there'll be PYTHON, PYTHON36 and PYTHON37 environment variables, and PYTHON will point to 3.7).

Copyright © 2021 Niklas Rosenstein

Comments
  • Newer readthedocs-custom-steps fails where 0.5.1 works

    Newer readthedocs-custom-steps fails where 0.5.1 works

    Thanks for this helpful tool.

    If I remove the ==0.5.1 from the requirements below, the documentation is not built correctly - it passes but all I see when browsing is: "Welcome to Read the Docs This is an autogenerated index file.

    Please create an index.md or README.md file with your own content under the root (or /docs) directory in your repository."

    .readthedocs-requirements.txt

    pydoc-markdown
readthedocs-custom-steps==0.5.1

    .readthedocs.yaml

    version: 2
mkdocs: {}  # tell readthedocs to use mkdocs
python:
  version: 3.7
  install:
  - method: pip
    path: .
  - requirements: docs/.readthedocs-requirements.txt

    .readthedocs-custom-steps.yml

    steps:
- |
  pydoc-markdown --build --site-dir "$PWD/_build/html"

    I would like to get the latest version working so I can move the steps into pyproject.toml.

    Incidentally I've made an issue against readthedocs itself to see if they could allow specification of the requirements directly in .readthedocs.yaml to reduce the number of configuration files further. Sadly readthedocs won't support pyproject.toml.

    bug 
    opened by mcarans 7
  • Doesn't work anymore

    Doesn't work anymore

    Was really excited to use this to run a shell script that installs rust, but it doesn't seem to work.

    image

    It builds a wheel, and as a result, no custom steps :(

    I use https://github.com/daggy1234/polaroid . All files there

    opened by Daggy1234 6
  • recursively look for .readthedocs-custom-steps.yml so it can be outside top-level root

    recursively look for .readthedocs-custom-steps.yml so it can be outside top-level root

    Implements a recursive search for .readthedocs-custom-steps.yml thus allowing this file to exist outside of the top-level root.

    This hence allows all the documentation configuration files exist outside of the root and together in a /docs/ path for example -

    • in the file .readthedocs.yml we point to requirements: docs/.readthedocs-requirements.txt
    • we invoke pydoc-markdown via .readthedocs-custom-steps.yml by naming the config file pydoc-markdown --build --site-dir $SITE_DIR -vv docs/pydoc-markdown.yml
    opened by ndejong 1
  • Provide PYTHON environment variable

    Provide PYTHON environment variable

    python is not on the PATH inside the RTD build environment. But there is an interpreter available at /home/docs/.pyenv/shims/python3.7. We could provide a PYTHON environment variable pointing to that interpreter (preferably dynamically).

    enhancement 
    opened by NiklasRosenstein 0
  • Search for config file in additional locations

    Search for config file in additional locations

    As discussed in #1 , it would be good to look for the configuration file in additional locations aside from the project root. I suggest the following order:

    1. .readthedocs-custom-steps.yml
    2. docs/.readthedocs-custom-steps.yml
    3. relative to the requirements.txt file(s) specified in the .readthedocs.yml config file
    enhancement 
    opened by NiklasRosenstein 0
Owner
Niklas Rosenstein
Niklas Rosenstein
GitHub
Run `black` on python code blocks in documentation files

blacken-docs Run black on python code blocks in documentation files. install pip install blacken-docs usage blacken-docs provides a single executable

Anthony Sottile 460 Dec 23, 2022
Demonstration that AWS IAM policy evaluation docs are incorrect

The flowchart from the AWS IAM policy evaluation documentation page, as of 2021-09-12, and dating back to at least 2018-12-27, is the following: The f

Ben Kehoe 15 Oct 21, 2022
💻An open-source eBook with 101 Linux commands that everyone should know

This is an open-source eBook with 101 Linux commands that everyone should know. No matter if you are a DevOps/SysOps engineer, developer, or just a Linux enthusiast, you will most likely have to use the terminal at some point in your career.

Ashfaque Ahmed 0 Oct 29, 2022
Main repository for the Sphinx documentation builder

Sphinx Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects (or other documents consisting of mul

null 5.1k Jan 2, 2023
A curated list of awesome tools for Sphinx Python Documentation Generator

Awesome Sphinx (Python Documentation Generator) A curated list of awesome extra libraries, software and resources for Sphinx (Python Documentation Gen

Hyunjun Kim 831 Dec 27, 2022
API Documentation for Python Projects

API Documentation for Python Projects. Example pdoc -o ./html pdoc generates this website: pdoc.dev/docs. Installation pip install pdoc pdoc is compat

mitmproxy 1.4k Jan 7, 2023
Literate-style documentation generator.

888888b. 888 Y88b 888 888 888 d88P 888 888 .d8888b .d8888b .d88b. 8888888P" 888 888 d88P" d88P" d88""88b 888 888 888

Pycco 808 Dec 27, 2022
Main repository for the Sphinx documentation builder

Sphinx Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects (or other documents consisting of mul

null 5.1k Jan 4, 2023
Project documentation with Markdown.

MkDocs Project documentation with Markdown. View the MkDocs documentation. Project release notes. Visit the MkDocs wiki for community resources, inclu

MkDocs 15.6k Jan 2, 2023
Watch a Sphinx directory and rebuild the documentation when a change is detected. Also includes a livereload enabled web server.

sphinx-autobuild Rebuild Sphinx documentation on changes, with live-reload in the browser. Installation sphinx-autobuild is available on PyPI. It can

Executable Books 440 Jan 6, 2023
Your Project with Great Documentation.

Read Latest Documentation - Browse GitHub Code Repository The only thing worse than documentation never written, is documentation written but never di

Timothy Edmund Crosley 809 Dec 28, 2022
:blue_book: Automatic documentation from sources, for MkDocs.

mkdocstrings Automatic documentation from sources, for MkDocs. Features Python handler features Requirements Installation Quick usage Features Languag

Timothée Mazzucotelli 1.1k Dec 31, 2022
:blue_book: Automatic documentation from sources, for MkDocs.

mkdocstrings Automatic documentation from sources, for MkDocs. Features - Python handler - Requirements - Installation - Quick usage Features Language

null 1.1k Jan 4, 2023
📖 Generate markdown API documentation from Google-style Python docstring. The lazy alternative to Sphinx.

lazydocs Generate markdown API documentation for Google-style Python docstring. Getting Started • Features • Documentation • Support • Contribution •

Machine Learning Tooling 118 Dec 31, 2022
Seamlessly integrate pydantic models in your Sphinx documentation.

Seamlessly integrate pydantic models in your Sphinx documentation.

Franz Wöllert 71 Dec 26, 2022
Documentation generator for C++ based on Doxygen and mosra/m.css.

mosra/m.css is a Doxygen-based documentation generator that significantly improves on Doxygen's default output by controlling some of Doxygen's more unruly options, supplying it's own slick HTML+CSS generation and adding a fantastic live search feature.

Mark Gillard 109 Dec 7, 2022
NetBox plugin for BGP related objects documentation

Netbox BGP Plugin Netbox plugin for BGP related objects documentation. Compatibility This plugin in compatible with NetBox 2.10 and later. Installatio

Nikolay Yuzefovich 133 Dec 27, 2022
Automated Integration Testing and Live Documentation for your API

Automated Integration Testing and Live Documentation for your API

ScanAPI 1.3k Dec 30, 2022
Documentation of the QR code found on new Austrian ID cards.

Austrian ID Card QR Code This document aims to be a complete documentation of the format used in the QR area on the back of new Austrian ID cards (Per

Gabriel Huber 9 Dec 12, 2022