Skip to content
GitLab

Documentation update process · Changes

Page history
Re-write for move to mathjax-docs repository and docs.mathjax.org -- new release process authored by pkra's avatar pkra
Show whitespace changes
Inline Side-by-side
Documentation-update-process.md
View page @ 67c746d9
> This will require an update/simplification as soon as the documentation is hosted on github-pages.
The MathJax documentation is stored in the docs directory of the MathJax GitHub repository. The docs/source directory contains the master .rst files, and there is a makefile in docs that allows you to convert these to the various formats needed by MathJax.
### To rebuild the html directory that is part of the repository
1. First, cd to the docs directory: ` cd MathJax/docs `
1. Remove the current html and .doctrees directories: `rm -rf html .doctrees`
1. Remake the html documentation: `make html`
1. Commit the changes to GitHub: `git commit -a -m "(log message about changes)"`
### To rebuild the documentation for www.mathjax.org
1. First, cd to the docs directory: `cd MathJax/docs`
1. Remove the current html and .doctrees directries: `rm -rf html .doctrees`
1. Remake the html documentation with headers for www.mathjax.org: `make html-mathjax-site`
1. Rename the html-mathjax-site directory to the version number for the documentation: `mv html-mathjax-site N.M`
1. Remove the .buildinfo and objects.inv files: `rm N.M/.buildinfo N.M/objects.inv`
1. Create a tar archive of the directory: `tar cvfz N.M.tgz N.M`
1. Move the directory to webfactional: `scp N.M.tgz (user)@dessci.webfactional.com`
(fill in the user appropriately).
1. Log into webfactional: `ssh (user)@dessci.webfactional.com`
1. Unpack & delete the archive: `tar vfxz N.M.tgz && rm N.M.tgz`
1. Move to the docs directory: `cd webapps/wp/docs`
1. If you are replacing an existing documentation directory:`mv N.M N.M-old && mv ~/N.M . && rm -rf N.M-old`
1. Otherwise (this is documentation for a new version)
1. Move the documentation directory: `mv ~/N.M .`
1. Edit the index.html to point to the new documentation.
1. Edit the documentation page (using the Wordpress interface) to include the new documentation directory.
1. Log out of webfactional: `logout`
1. Check that the documentation page shows up correctly by loading [http://www.mathjax.org/docs/](http://www.mathjax.org/docs/) (you might need to clear the history first).
The **version number of the documentation** is in html/source/config.py and should be changed when the version of MathJax changes.
The www.mathjax.org header information is stored in html/source/mjtheme/layout.html and should be updated if the theme at www.mathjax.org changes. In particular, if items are added to or removed from the main menu, these need to be added to or removed from layout.html by hand.
\ No newline at end of file
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 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.
### 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.
### Release process checklist
> This assumes you have [Sphinx](http://sphinx.pocoo.org/) installed (and git, of course).
0. This is part of the [[Release process checklist]] so `vN.M-latest` is assumed to come from there.
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. 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/>.
### Appendix: Understanding the process
Up to MathJax v2.0, the documentation was stored in the main repository. Of course, with git versioning, older branches do contain these older docs.
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. It's best to modify the `v1.0` branch and merge the changes into the others.
**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.
```
#/bin/bash
cd /tmp
git clone https://github.com/mathjax/mathjax-docs.git
cd mathjax-docs
for remote in `git branch -r | grep -v master `; do git checkout --track $remote ; done
git checkout v1.0
sphinx-build . temp/en/v1.0/
git checkout v1.1-latest
sphinx-build . temp/en/v1.1-latest/
git checkout v2.0-latest
sphinx-build . temp/en/v2.0-latest/
git checkout v2.1-latest
sphinx-build . temp/en/v2.1-latest/
git checkout master
sphinx-build . temp/en/latest/
git checkout gh-pages
rm -Rf "en/"
mv "temp/en" .
rmdir "temp"
rm -rf "en/latest/.doctrees"
rm -rf "en/v2.0-latest/.doctrees"
rm -rf "en/v1.1-latest/.doctrees"
rm -rf "en/v1.0/.doctrees"
rm -rf "en/latest/.buildinfo"
rm -rf "en/v2.0-latest/.buildinfo"
rm -rf "en/v1.1-latest/.buildinfo"
rm -rf "en/v1.0/.buildinfo"
```
Then make sure that everything compiled nicely and commit and push the changes.
```
git commit -a -m "(log message about changes)"
git push origin gh-pages
```
And of course, update the CDN with `en/`.