doc environment in tox failing on travis

[tamuri]

Looks like it's to do with links to base classes - they are not passing link check e.g.:

writing output... [ 36%] reference/tlo.methods.antenatal_care
(line   11) broken    ./tlo.core.html#tlo.core.Module -
(line   71) broken    ./tlo.events.html#tlo.events.RegularEvent -
(line   73) broken    ./tlo.events.html#tlo.events.Event -
(line   75) broken    ./tlo.events.html#tlo.events.PopulationScopeEventMixin -
(line   92) broken    ./tlo.methods.healthsystem.html#tlo.methods.healthsystem.HSI_Event -
(line   94) broken    ./tlo.events.html#tlo.events.IndividualScopeEventMixin -
(line  117) broken    ./tlo.methods.healthsystem.html#tlo.methods.healthsystem.HSI_Event -
(line  142) broken    ./tlo.methods.healthsystem.html#tlo.methods.healthsystem.HSI_Event -
(line  144) broken    ./tlo.events.html#tlo.events.IndividualScopeEventMixin -
(line  119) broken    ./tlo.events.html#tlo.events.IndividualScopeEventMixin -
(line  167) broken    ./tlo.methods.healthsystem.html#tlo.methods.healthsystem.HSI_Event -
(line  169) broken    ./tlo.events.html#tlo.events.IndividualScopeEventMixin -
(line  192) broken    ./tlo.methods.healthsystem.html#tlo.methods.healthsystem.HSI_Event -
(line  194) broken    ./tlo.events.html#tlo.events.IndividualScopeEventMixin -

[tamuri]

I believe related PR sphinx-doc/sphinx#8245

(3.3.0 is new release of Sphinx, which Tox is now using for testing)

[mattagape]

Hi @tamuri. I get errors like this when I was building the docs on my own machine. But the links do work, in fact.

e.g. I just built the docs (with tox -e docs) and saw errors including the following:

writing output... [ 87%] reference/tlo.methods.tb_hs_engagement ( line 11) broken ./tlo.core.html#tlo.core.Module -

I then started up an HTTP server on my machine and navigated to the doc page for tlo.methods.tb_hs_engagement and found the (apparently sole) link to tlo.core.Module. Clicking on it took me to the Module page no problem.

So I think these errors are spurious.

[tamuri]

They work but I don't think the errors are spurious.

Sphinx is generating the HTML anchor tags with style "reference external" i.e. <a class="reference external" href="./tlo.core.html#tlo.core.Module">

The way this link is added to the rst needs to be an internal link: <a class="reference internal" href="tlo.core.html#tlo.core.Module">

I believe the right way to reference a class/method is cross-referencing the Python objects (see here).

I would say to look at the rst files that are generated from the autodoc'd rst (i.e. the TLO framework rst files) to see the types of links they use to link base classes. But there doesn't seem to be a way to get access to that.

[tamuri]

Here's an example of generated RST from an autodoc RST:

.. py:class:: RegularEvent(module, *, frequency, end_date=None)
   :module: tlo.events

   Bases: :class:`tlo.events.Event`

   An event that automatically reschedules itself at a fixed frequency.


   .. py:method:: RegularEvent.post_apply_hook()
      :module: tlo.events

      Schedule the next occurrence of this event.

See link construction for item after "Bases:". I think this is how we should be linking to an internal python classes. I'd also format the list of bases similarly to the generated documentation (i.e. a comma-separated list of internal reference links rather than a list with "base 1" "base 2" etc.

:class: `tlo.events.Event`

We might need to explicitly set the Python domain, I don't know i.e.

:py:class: `tlo.events.Event`

[tamuri]

Do you think you can get to this today @mattgillucl?

[mattagape]

Working on it (in-between meetings!)

[mattagape]

I was just looking at tlo.util.html (and others). It's not one that my code generates.

An internal link seems to be similar to the external ones:
e.g. <a class="reference internal" href="../_modules/tlo/util.html#BitsetHandler.is_empty">

Nevertheless, I will try changing the output strings I write to the .rst files (referring to their base classes), and see if that works.

[tamuri]

I don't believe the generated HTML is the problem (apart from the internal/external class). It's how the link is written in the RST.

[mattagape]

OK I have a branch mattdocfix on which I have just pushed a commit. That removes almost all the errors. I am still getting one broken link error.
So it looks promising. A bonus now is that the list of base classes is more like that in the part of the docs I haven't touched.

NB A string like

:class: `tlo.events.Event`

must have the space removed, i.e. should be

:class:`tlo.events.Event`

I am getting a lot of "unexpected indentation" errors, but I think that happens normally??

[tamuri]

Thanks. Please set up your branch as a PR and we can see whether it succeeds on Travis.

[tamuri]

Can you fix the one broken link error - any error will cause build to fail.

[mattagape]

OK, on my local machine I ran tox -e docs and then cat dist/docs/output.txt. As well as a message about readme.rst being redirected permanently was the line:
reference/tlo.docs.rst:2: [broken] ./tlo.core.html#tlo.core.Module:

Contents of TLOmodel/docs/reference/tlo.docs.rst:

tlo.docs module
===============

.. automodule:: tlo.docs
   :members:
   :undoc-members:
   :show-inheritance:

There's nothing obviously wrong with it, so I don't know what the problem is (assuming it is indeed this).

[mattagape]

Yes, this does seem to be the problem. Just ran the build again on my machine:

...
writing output... [ 21%] reference/tlo.docs                                                                                             
(line    2) broken    ./tlo.core.html#tlo.core.Module - 
...

But the fault isn't obvious.

[mattagape]

I don't think reference/tlo/docs.py should have a link to tlo.core.Module; could this be a tox or sphinx config file error??

[tamuri]

Fixed in PR #205