# 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.
<br/><br/>

## 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.
<br/><br/>

## 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](../strategies/infrastructure/documentation-generation.md).

## References

- [Sphinx Quick Start Guide](https://cerodell.github.io/sphinx-quickstart-guide/build/html/install.html#installation)
- [Sphinx Directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html)
- [Sphinx Configuration (conf.py)](https://www.sphinx-doc.org/en/master/usage/configuration.html)
- [Sphinx Themes](https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html)