[rtems-docs commit] Render math via JavaScript in HTML output

[Chris Johns]

On 21/02/2017 18:05, Sebastian Huber wrote:
> On 21/02/17 00:25, Chris Johns wrote:
>> Any new extensions need to have a waf check added before being pushed
>> to the repo. A build failure is not an acceptable way to manage a user
>> not having the extension installed, we need waf's configure to handle
>> this. We may also need to figure out what happens with the result of
>> the check, ie output specific extension control.
>
> Where can I add this test?

The test goes in common/waf.py. I am working on something.

> There are some extensions in
>
> common/conf.py
>
> Is this file used for the tests? Is it enough to do this:

Assuming we have working tests for the configure phase and based on your 
testing I think both these extensions can enabled all the time so adding 
them to common/conf.py is ok.

We only need conditional extensions if they create a clash with the 
different output formats, for example HTML needing Tex because an 
extension needs Tex. We need to look for extensions that avoid this 
before heading down this path.

> diff --git a/c-user/conf.py b/c-user/conf.py
> index 18b3206..90a7af7 100644
> --- a/c-user/conf.py
> +++ b/c-user/conf.py
> @@ -3,8 +3,6 @@ sys.path.append(os.path.abspath('../common/'))
>
>  from conf import *
>
> -extensions = ['sphinx.ext.mathjax', 'sphinxcontrib.bibtex']

Yes to this change, we should discourage per doc extensions. A supported 
extension should be available to all docs.

> -
>  version = '4.11.99'
>  release = '4.11.99'
>
> diff --git a/common/conf.py b/common/conf.py
> index 9f6bace..03cfa44 100644
> --- a/common/conf.py
> +++ b/common/conf.py
> @@ -31,7 +31,8 @@ extensions = [
>         "sphinx.ext.doctest",
>         "sphinx.ext.graphviz",
>         "sphinx.ext.intersphinx",
> -       "sphinx.ext.pngmath",
> +       "sphinx.ext.mathjax",
> +       "sphinxcontrib.bibtex",
>         "rtemsext",
>         "rtemsdomain",
>  ]

The other solution which Amar suggested is to embed the extension in the 
repo. I suspect this is what he has done with sphinx.ext.intersphinx 
etc. My only concern is managing any version skew between the user 
installed Sphinx and our local extensions. I have no idea if this is an 
issue and how stable the APIs in Sphinx are the extensions use.

Chris