Skip to content
GitLab

Documentation update process · Changes

Page history
re-write for switch to ReadTheDocs -- updating is much simpler now :) authored by pkra's avatar pkra
Hide whitespace changes
Inline Side-by-side
Documentation-update-process.md
View page @ c7dbb2f7
The MathJax documentation is stored in its own GitHub repository, [mathjax-docs](http://github.com/mathjax/mathjax-docs/) and we host a compiled copy at <http://docs.mathjax.org>.
The MathJax documentation is written in restructuredText/[sphinx-doc](http://sphinx.pocoo.org/) and stored in its own GitHub repository, [mathjax-docs](http://github.com/mathjax/mathjax-docs/). We host a compiled copy at <http://docs.mathjax.org>.
The repository follows the versioning of the main repository (with branches v1.0, v1.1-latest, v2.0-latest etc). These "main" branches contain the master .rst files of each version. There is an additional orphaned branch, `gh-pages`, containing a compiled version of the documentation for all versions.
The repository follows the versioning of the main repository (with branches v1.0, v1.1-latest, v2.0-latest etc) with one important difference: we add new branches only upon the **next** release, i.e., `master` corresponds to `latest` and there is no separate branch for the latest version.
### How does it work?
The repository contains the source.The compiled copy at <docs.mathjax.org> is provided through [ReadTheDocs](http://www.rtfd.org), i.e., `docs.mathjax.org` is a CNAME for `mathjax.rtfd.org`. They also provide the documentation as downloads.
ReadTheDocs is a free service sponsored by Python, Mozilla et al to provide automatic compilation of sphinx-doc. A webhook in the settings of a github repository will trigger compilation of the docs whenever the repository changes. ReadTheDocs also provides zipped, PDF and epub versions of each branch. Which branches are compiled can be configured through the ReadTheDocs user account.
### Updating the documentation
The easiest way to update a particular page is to visit the respective page at <http://docs.mathjax.org> and click on the `Edit source (on GitHub)` link. This takes you to the corresponding `blob`-view on github where you can simply click `Edit` (you need to be a logged-in Github user for editing).
When you save your changes version, GitHub automatically creates a fork (if it doesn't exist) and creates a pull request. Easy as that.
When you save your changes version, GitHub automatically creates a fork (if it doesn't exist) and creates a pull request. The MathJax Team will accept or reject it -- and ReadTheDocs will build it automatically. Easy as that.
### Release process checklist
(For creating new pages, you will still have to clone the repository and submit a pull request.)
> This assumes you have [Sphinx](http://sphinx.pocoo.org/) installed (and git, of course).
### Release process checklist
0. This is part of the [[Release process checklist]] so `vN.M-latest` is assumed to come from there.
0. This is part of the [[Release process checklist]].
1. Clone the repository `git clone https://github.com/mathjax/mathjax-docs.git`
1. Track all branches, e.g., in bash: ``for remote in `git branch -r | grep -v master `; do git checkout --track $remote ; done``
1. Create the new branch `vN.M-latest` and tag according to the release process.
1. In the new branch, update the version number in the Sphinx configuration file `config.py`.
1. Commit & push pack to github: `git commit -a -m "(log message about new branch)" &&
git push origin vN.M-latest`
1. Build the HTML for the new branch `sphinx-build . vN.M-latest/` (this creates a new folder `vN.M-latest`).
1. Check out the release before the new release say `vA.B-latest`.
2. Change the theme of `vA.B-latest` to add the version warning: modify `_theme/sphinx-bootstrap/layout.html` (see older branches for the code snippet).
1. Update the `sourcelink` in `_templates` to point to the branch (not `master`).
1. Build the HTML for the branch `sphinx-build . vA.B-latest/`.
1. Checkout the `gh-pages` branch: `git checkout gh-pages` (this will leave the new folders in place).
1. Move the new folders to `en/.`
1. Replace `en/latest` with a copy of the `vN.M-latest` folder.
1. Commit & push pack to github `git commit -a -m "(log message about new branch)" && git push origin gh-pages`
1. Update the `mathjax-docs` container on the CDN with `en/`.
1. Update <http://www.mathjax.org/resources/docsindex/>.
1. Create a branch corresponding to the **current** version, i.e., the version that will be replaced by the new release.
1. In that "current" branch, modify
* the edit-on-github link `_templates/sourcelink.html` to point to the "current" branch.
* the theme layout `_themes/sphinx-bootstrap/layout.html`: add the version-warning to the quick-links:
* After `<li><strong>Quick links</strong></li>` insert `<li> <a class="btn btn-mini btn-success" href="http://docs.mathjax.org/">Newer version available!</a> </li>`
1. Commit & push pack to github: `git commit -a -m "(log message about the 'current' branch)" &&
git push origin (current branch)`
1. Checkout the `master` branch,
* update the version number in the Sphinx configuration file `config.py`.
1. Commit & push pack to github: `git commit -a -m "(log message about version change)" &&
git push origin master`
### Appendix: Understanding the process
......@@ -37,21 +38,20 @@ Up to MathJax v2.0, the documentation was stored in the main repository. Of cour
With MathJax v2.1, we decided to separate the documentation and give it its own repository. That `mathjax-docs` repository was created by trimming the main repository down to the documentation's source folder. Accordingly, the entire git history of the documentation sources is present in the `mathjax-docs` repository.
We also provide downloads via [Read The Docs](https://readthedocs.org/projects/mathjax/downloads/). These are generated automatically whenever a change of the documentation is pushed (there's a webhook in the github repository settings for this).
If Read The Docs updates their jquery, we can host the documentation there directly; this would simplify things further.
### Appendix: Modifying the theme
If you have to work on the sphinx-theme (currently [sphinx-bootstrap]()), you should update all branches. Due to the hacks in the theme, you'll have to do this manually for each branch.
The current theme is a [fork of sphinx-bootstrap](https://github.com/pkra/sphinx-bootstrap) by Scotch Media.
Hacks include:
* the sphinx-bootstrap `layout.html` contains version-warning button -- which is only appropriate for older versions
* the `sourcelink` in templates is different for each version.
If you have to work on the theme, make sure you update all branches! Due to the hack in the theme, you'll have to do this manually for the older branches vs the master branch to take the version-warning-button into account.
Also note: the `sourcelink` in templates is different for each version since it points to the corresponding branch on github.
**Warning** There's one difference between the theme in the latest branch and all others: the theme for older branches contains a version warning! Be sure to check that you didn't add the version warning to the branch of the current version and the master branch.
Here's a bash script to rebuild the html for multiple versions.
### Appendix: a bash script for hosting via github-pages.
In case you ever need it, here's a bash script we used to rebuild the html for multiple versions and hosting through github-pages.
```
#/bin/bash
......@@ -90,4 +90,4 @@ git commit -a -m "(log message about changes)"
git push origin gh-pages
```
And of course, update the CDN with `en/`.
And of course, update the CDN with `en/`.
\ No newline at end of file