Introduction

A document on how to publish documents.

To publish markdown content to a web site, we use a tool called Sphinx to build html content from markdown, publish the content to a repo branch and then integrate that branch with GitHub Pages. GitHub Pages provisions a web site and uses the content in the branch for the site.

Local Setup

To setup and run Sphinx locally:

  1. Install Python

  2. Using the Python pip tool:

   pip install sphinx
   pip install myst-parser

Configuration

It’s easiest if your markdown resides in its own separate directory (e.g. “docs” or “documentation”).

Assuming documentation, within the documentation subdirectory, create conf.py and index.rst files. Also in documentation create the custom.css in the _static/css subdirectory. Tip: it’s best to just copy these from an existing repo such as this one and modify them. For custom.css, you can use it as-is.

conf.py is the configuration that controls parsing, theming, inclusion/exclusion patterns and more.

index.rst is the structure definition. You need one in the root of docs and optionally will have them in subdirectories to control layout within those subdirectories. Tip: using the glob selector is the best way to get all markdown within a subdirectory to avoid having to list names individually.

Building/Testing Locally

To build your content locally, execute the command:

sphinx-build -b html ../docs _build/html

Common errors when building your content:

  • Markdown headers not in progressive order from H1 to H2 to H3

  • Markdown that ends in separator lines

Tip: It is important that users of your repo understand how documentation is structured and built. If they are adding markdown files to an existing directory, as long as you are using a glob pattern, that documentation will automatically get published. If they are adding markdown files to a new directory, they will also need to update the index.rst or the new markdown will not get picked up by Sphinx.

To validate your content:

Navigate to the _build/html directory and open index.html in your browser.

Tip: When rebuilding, it is best to first delete the _build directory before re-running the sphinx-build command.

Publishing Documentation

Great, you have generated standard web documentation from your markdown files. But you are the only viewer. To publish your documentation to the web for others within Seagen to view, check out the document Documentation Generation.

References