|
|
> This will require an update/simplification as soon as the documentation is hosted on github-pages.
|
|
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 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.
|
|
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.
|
|
|
|
|
|
|
|
### To rebuild the html directory that is part of the repository
|
|
### Updating the documentation
|
|
|
|
|
|
|
|
1. First, cd to the docs directory: ` cd MathJax/docs `
|
|
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).
|
|
|
1. Remove the current html and .doctrees directories: `rm -rf html .doctrees`
|
|
|
|
|
1. Remake the html documentation: `make html`
|
|
When you save your changes version, GitHub automatically creates a fork (if it doesn't exist) and creates a pull request. Easy as that.
|
|
|
1. Commit the changes to GitHub: `git commit -a -m "(log message about changes)"`
|
|
|
|
|
|
|
### Release process checklist
|
|
|
|
|
|
|
|
### To rebuild the documentation for www.mathjax.org
|
|
> This assumes you have [Sphinx](http://sphinx.pocoo.org/) installed (and git, of course).
|
|
|
|
|
|
|
|
1. First, cd to the docs directory: `cd MathJax/docs`
|
|
0. This is part of the [[Release process checklist]] so `vN.M-latest` is assumed to come from there.
|
|
|
1. Remove the current html and .doctrees directries: `rm -rf html .doctrees`
|
|
1. Clone the repository `git clone https://github.com/mathjax/mathjax-docs.git`
|
|
|
1. Remake the html documentation with headers for www.mathjax.org: `make html-mathjax-site`
|
|
1. Track all branches, e.g., in bash: ``for remote in `git branch -r | grep -v master `; do git checkout --track $remote ; done``
|
|
|
1. Rename the html-mathjax-site directory to the version number for the documentation: `mv html-mathjax-site N.M`
|
|
1. Create the new branch `vN.M-latest` and tag according to the release process.
|
|
|
1. Remove the .buildinfo and objects.inv files: `rm N.M/.buildinfo N.M/objects.inv`
|
|
1. In the new branch, update the version number in the Sphinx configuration file `config.py`.
|
|
|
1. Create a tar archive of the directory: `tar cvfz N.M.tgz N.M`
|
|
1. Commit & push pack to github: `git commit -a -m "(log message about new branch)" &&
|
|
|
1. Move the directory to webfactional: `scp N.M.tgz (user)@dessci.webfactional.com`
|
|
git push origin vN.M-latest`
|
|
|
(fill in the user appropriately).
|
|
1. Build the HTML for the new branch `sphinx-build . vN.M-latest/` (this creates a new folder `vN.M-latest`).
|
|
|
1. Log into webfactional: `ssh (user)@dessci.webfactional.com`
|
|
1. Check out the release before the new release say `vA.B-latest`.
|
|
|
1. Unpack & delete the archive: `tar vfxz N.M.tgz && rm N.M.tgz`
|
|
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. Move to the docs directory: `cd webapps/wp/docs`
|
|
1. Build the HTML for the branch `sphinx-build . vA.B-latest/`.
|
|
|
1. If you are replacing an existing documentation directory:`mv N.M N.M-old && mv ~/N.M . && rm -rf N.M-old`
|
|
1. Checkout the `gh-pages` branch: `git checkout gh-pages` (this will leave the new folders in place).
|
|
|
1. Otherwise (this is documentation for a new version)
|
|
1. Move the new folders to `en/.`
|
|
|
1. Move the documentation directory: `mv ~/N.M .`
|
|
1. Replace `en/latest` with a copy of the `vN.M-latest` folder.
|
|
|
1. Edit the index.html to point to the new documentation.
|
|
1. Commit & push pack to github `git commit -a -m "(log message about new branch)" && git push origin gh-pages`
|
|
|
1. Edit the documentation page (using the Wordpress interface) to include the new documentation directory.
|
|
1. Update the `mathjax-docs` container on the CDN with `en/`.
|
|
|
1. Log out of webfactional: `logout`
|
|
1. Update <http://www.mathjax.org/resources/docsindex/>.
|
|
|
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).
|
|
|
|
|
|
|
### Appendix: Understanding the process
|
|
|
The **version number of the documentation** is in html/source/config.py and should be changed when the version of MathJax changes.
|
|
|
|
|
|
|
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.
|
|
|
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 |
|
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/`. |
pkra