|
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
|
|
### 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).
|
|
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. 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 a branch corresponding to the **current** version, i.e., the version that will be replaced by the new release.
|
|
1. Create the new branch `vN.M-latest` and tag according to the release process.
|
|
1. In that "current" branch, modify
|
|
1. In the new branch, update the version number in the Sphinx configuration file `config.py`.
|
|
* the edit-on-github link `_templates/sourcelink.html` to point to the "current" branch.
|
|
1. Commit & push pack to github: `git commit -a -m "(log message about new branch)" &&
|
|
* the theme layout `_themes/sphinx-bootstrap/layout.html`: add the version-warning to the quick-links:
|
|
git push origin vN.M-latest`
|
|
* 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. Build the HTML for the new branch `sphinx-build . vN.M-latest/` (this creates a new folder `vN.M-latest`).
|
|
1. Commit & push pack to github: `git commit -a -m "(log message about the 'current' branch)" &&
|
|
1. Check out the release before the new release say `vA.B-latest`.
|
|
git push origin (current branch)`
|
|
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. Checkout the `master` branch,
|
|
1. Update the `sourcelink` in `_templates` to point to the branch (not `master`).
|
|
* update the version number in the Sphinx configuration file `config.py`.
|
|
1. Build the HTML for the branch `sphinx-build . vA.B-latest/`.
|
|
1. Commit & push pack to github: `git commit -a -m "(log message about version change)" &&
|
|
1. Checkout the `gh-pages` branch: `git checkout gh-pages` (this will leave the new folders in place).
|
|
git push origin master`
|
|
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
|
|
### Appendix: Understanding the process
|
|
|
|
|
... | @@ -37,21 +38,20 @@ Up to MathJax v2.0, the documentation was stored in the main repository. Of cour |
... | @@ -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.
|
|
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
|
|
### 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:
|
|
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.
|
|
* 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.
|
|
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.
|
|
**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
|
|
#/bin/bash
|
... | @@ -90,4 +90,4 @@ git commit -a -m "(log message about changes)" |
... | @@ -90,4 +90,4 @@ git commit -a -m "(log message about changes)" |
|
git push origin gh-pages
|
|
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 |