|
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 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) with one difference: before a new release, we merge the `master` branch into the branch for the current release for a final update of that branch.
|
|
The repository follows the versioning of the main repository (with branches v1.0, v1.1-latest, v2.0-latest etc).
|
|
|
|
|
|
### How does it work?
|
|
### 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.
|
|
The github repository contains the sphinx source. The compiled copy at <docs.mathjax.org> is provided through the awesome services of [ReadTheDocs](http://www.rtfd.org), i.e., `docs.mathjax.org` is a CNAME for `mathjax.rtfd.org`. RTD 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.
|
|
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.
|
|
|
|
|
... | @@ -12,9 +12,9 @@ ReadTheDocs is a free service sponsored by Python, Mozilla et al to provide auto |
... | @@ -12,9 +12,9 @@ ReadTheDocs is a free service sponsored by Python, Mozilla et al to provide auto |
|
|
|
|
|
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. The MathJax Team will accept or reject it -- and ReadTheDocs will build it automatically. 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 review it and ReadTheDocs will build it automatically. Easy as that.
|
|
|
|
|
|
(For creating new pages, you will still have to clone the repository and submit a pull request.)
|
|
(For creating new pages, you can use the GitHub interface as well.)
|
|
|
|
|
|
### Release process checklist
|
|
### Release process checklist
|
|
|
|
|
... | @@ -30,30 +30,9 @@ When you save your changes version, GitHub automatically creates a fork (if it d |
... | @@ -30,30 +30,9 @@ When you save your changes version, GitHub automatically creates a fork (if it d |
|
* Document all new features.
|
|
* Document all new features.
|
|
* Note: The `master` branch will always be the one to keep up-to-date, being visible at docs.mathjax.org/en/latest.
|
|
* Note: The `master` branch will always be the one to keep up-to-date, being visible at docs.mathjax.org/en/latest.
|
|
1. Log into ReadTheDocs and add the `vN.m-latest` branch to the build list.
|
|
1. Log into ReadTheDocs and add the `vN.m-latest` branch to the build list.
|
|
1. Check if docs.mathjax.org has the new build for v2.2
|
|
|
|
1. Merge `vN.m-latest` back into `master`.
|
|
1. Merge `vN.m-latest` back into `master`.
|
|
1. Push `vN.m-latest` and `master` back to github. `git push origin master vN.m-latest`
|
|
1. Push `vN.m-latest` and `master` back to github. `git push origin master vN.m-latest`
|
|
1. After(!) the release, modify the `vN.m-latest` branch (Note: this branch will have to be updated updated manually but will allow people to have a stable link for documentation of that version)
|
|
1. Check if docs.mathjax.org has the new build for `vN.m-latest`
|
|
* the edit-on-github link `_templates/sourcelink.html` to point to the `current` branch. ((**pkra:** this may be unnecessary, I think rtfd now adds it to the sidebar and this might not have any effect anymore))
|
|
|
|
* 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>` (this may seem counter-intuitive, but `latest` is designed to be more up-to-date.
|
|
|
|
* Add canonical link to `vN.m-latest` branch theme layout.
|
|
|
|
```
|
|
|
|
<link rel="canonical" href="http://docs.mathjax.org/en/latest
|
|
|
|
{%- for word in pagename.split('/') -%}
|
|
|
|
{%- if word != 'index' -%}
|
|
|
|
{%- if word != '' -%}
|
|
|
|
/{{ word }}
|
|
|
|
{%- endif -%}
|
|
|
|
.html
|
|
|
|
{%- endif -%}
|
|
|
|
{%- endfor -%}
|
|
|
|
">
|
|
|
|
```
|
|
|
|
1. Commit & push pack to github: `git commit -a -m "(log message about the new release branch)" &&
|
|
|
|
git push origin "vN.m-latest"`.
|
|
|
|
1. Commit & push pack to github: `git commit -a -m "(log message about version change)" &&
|
|
|
|
git push origin master`
|
|
|
|
|
|
|
|
### Appendix: Understanding the process
|
|
### Appendix: Understanding the process
|
|
|
|
|
... | @@ -62,16 +41,6 @@ Up to MathJax v2.0, the documentation was stored in the main repository. Of cour |
... | @@ -62,16 +41,6 @@ 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.
|
|
|
|
|
|
|
|
|
|
### Appendix: Modifying the theme
|
|
|
|
|
|
|
|
The current theme is a [fork of sphinx-bootstrap](https://github.com/pkra/sphinx-bootstrap) by Scotch Media.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
### Appendix: a bash script for hosting via github-pages.
|
|
### 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.
|
|
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.
|
... | @@ -112,5 +81,3 @@ Then make sure that everything compiled nicely and commit and push the changes. |
... | @@ -112,5 +81,3 @@ Then make sure that everything compiled nicely and commit and push the changes. |
|
git commit -a -m "(log message about changes)"
|
|
git commit -a -m "(log message about changes)"
|
|
git push origin gh-pages
|
|
git push origin gh-pages
|
|
``` |
|
``` |
|
\ No newline at end of file |
|
|
|
|
|
|
|
And of course, update the CDN with `en/`. |
|
|
|
\ No newline at end of file |
|
|