-
Notifications
You must be signed in to change notification settings - Fork 4
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
doc environment in tox failing on travis #204
Comments
I believe related PR sphinx-doc/sphinx#8245 (3.3.0 is new release of Sphinx, which Tox is now using for testing) |
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
I then started up an HTTP server on my machine and navigated to the doc page for So I think these errors are spurious. |
They work but I don't think the errors are spurious. Sphinx is generating the HTML anchor tags with style "reference external" i.e. The way this link is added to the rst needs to be an internal link: 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. |
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` |
Do you think you can get to this today @mattgillucl? |
Working on it (in-between meetings!) |
I was just looking at An Nevertheless, I will try changing the output strings I write to the |
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. |
OK I have a branch NB A string like
must have the space removed, i.e. should be
I am getting a lot of "unexpected indentation" errors, but I think that happens normally?? |
Thanks. Please set up your branch as a PR and we can see whether it succeeds on Travis. |
Can you fix the one broken link error - any error will cause build to fail. |
OK, on my local machine I ran Contents of
There's nothing obviously wrong with it, so I don't know what the problem is (assuming it is indeed this). |
Yes, this does seem to be the problem. Just ran the build again on my machine:
But the fault isn't obvious. |
I don't think |
Fixed in PR #205 |
Looks like it's to do with links to base classes - they are not passing link check e.g.:
The text was updated successfully, but these errors were encountered: