Configure the build

The docs/conf.py file is the primary means of configuring the documentation build. For more information, see the Sphinx docs on configuration. There are additional HTML, JavaScript, and CSS files used to customize the output of the HTML build under _static and _templates. Much of the content in each of these files is identical across all IDM docsets.

When you create a new docset, these are the elements you must update with the project name or other unique information:

• conf.py

  • project: Include the project name.

  • rst_epilog: Leave the line in conf.py as-is, but remember to include a reuse/variables.txt file.

  • htmlhelp_basename: Include the project name.

  • latex_documents: Modify with project name.

  • man_pages: Modify with project name.

  • texinfo_documents: Modify with project name.

  • tags.add(‘project-name’): Modify with project name for conditionalizing text with the .. only directive in the Read the Docs build.

  • If the project includes API reference generated from docstrings, include:

    if sys.platform in ["linux", "darwin"]:
        subprocess.check_output(["make", "generate-api"], cwd=os.path.dirname(os.path.abspath(__file__)))
    else:
        subprocess.check_output(["make.bat", "generate-api"], cwd=os.path.dirname(os.path.abspath(__file__)))
    

• _templates/breadcrumbs.html: Update project name in the following line:

  <li><a href="{{ pathto(master_doc) }}">Project name</a> &raquo;</li>
  

• _templates/footer.html: Update the project name in the license statement.

• Makefile/make.bat

  • Update SPHINXOPTS with -t project-name to set the tag to use for conditionalizing text with the .. only directive in the local build.

  • If the project includes API reference generated from docstrings, include the generate-api code.

Read the Docs build

Read the Docs uses conf.py and .readthedocs.yml to configure the Sphinx build. The Makefile/make.bat files are not used directly by RTD. However, docsets that include API reference call generate-api in Makefile/make.bat through conf.py. See Read the Docs: Host the docs for more information.