WIP: Documentation fixes for Sphinx and website #540
Conversation
| Notes | ||
| ----- | ||
| The initial points of the Sobol' sequence has some repetition (see Table 2 | ||
| in Campolongo [1]_), which can be avoided by scrambling the sequence. | ||
| in Campolongo [1]__), which can be avoided by scrambling the sequence. |
There was a problem hiding this comment.
This should have been ok with the way references where listed in the reference section.
The fix in general works, an alternative was to make use of the refs in the text. Still I am surprised it was actually an issue in the first place as we have that in SciPy and don't call all the refs in the text.
There was a problem hiding this comment.
I wonder what plugins are in use for SciPy for the number style referencing?
At the moment, we get a large number of errors related to duplicate or unused references because the plugin expects the references to be globally unique. Most of the suggested solutions seem to be to switch to using bibtex style referencing, or to remove the reference system/plugin and just use simple numbered lists.
There was a problem hiding this comment.
@ConnectedSystems sorry for the delay. Right this is coming from numpydoc, see: https://numpydoc.readthedocs.io/en/latest/format.html#references
Maybe something to consider?
There was a problem hiding this comment.
Ah, so any references has to be used under the Notes section? That can be done I guess...
There was a problem hiding this comment.
It's not an obligation. You can have refs which are not being called (we have plenty in SciPy). Although might make sense long term to try to use what we cite, like in an paper.
Also you can call refs in the whole docstring, not only the Notes section.
There was a problem hiding this comment.
Hi @ConnectedSystems - please use semver for version numbers!
|
Hi @willu47 Yes, sorry - seems my understanding of semver is either outdated or I was misinformed from the beginning. I will endeavor to follow the official semver spec from now. |
I'm just nitpicking! It's not a big deal, but it does avoid issues further down the line. For example Pypi tends to be quite intolerant of version numbers that don't follow their conventions. Semver works fine with PyPi, although pypi does require a particular format for alpha or beta versions (see PEP440). PEP 440 does allow four levels |
|
To replace 1.4.6.1, you could yank it on PyPi and make a 1.4.7 |
ConnectedSystems
force-pushed
the
sphinx-error-fixes
branch
from
0e5f52a
to
fc4a59d
Compare
Turns out the citation references were being treated as global cross-references. Use across modules would then conflict with each other leading to the large number of warnings.
Turns out the citation references were being treated as global cross-references. Use across modules would then conflict with each other leading to the large number of warnings.
Turns out the citation references were being treated as global cross-references. Use across modules would then conflict with each other leading to the large number of warnings.
Turns out the citation references were being treated as global cross-references. Use across modules would then conflict with each other leading to the large number of warnings.
Turns out the citation references were being treated as global cross-references. Use across modules would then conflict with each other leading to the large number of warnings.
Turns out the citation references were being treated as global cross-references. Use across modules would then conflict with each other leading to the large number of warnings.
|
Errors/warnings reduced down to 21, mostly to do with duplicate descriptions, unexpected indentations (which I can't seem to resolve) and "unused references". I think these can be fixed later when I/someone has more energy to look into it. Included in this PR are a number of updates to the tutorials - primarily so that usage of the SALib Interface is properly showcased such that the documentation now matches with the examples in the recent paper. Given docs are fairly important, I will merge and release v1.4.7 shortly |
Work in progress PR.
Number of warnings/errors currently stand at 34 with these changes.
Addresses #532