Hi all! As you may know, most of the yt's docstrings are written using so called "numpy-style" [1]. It's not a default Sphinx's format and it requires an extension to parse it. Up till now we've been using numpydoc [2] to handle it. However, numpydoc is a bit buggy and not actively developed. My main issue with numpydoc is that it throws a bazillion of bogus warnings bloating jenkins logs to 100Mb for every docs' build.
There's an alternative extension: napoleon [3] that I'd like to try. The resulting documentation looks a bit different and it may also require a little bit of work to iron out the rough edges. I issued a PR 2238 [4] to show docs with the new look.
I'd appreciate your comments. Cheers, Kacper
[1] https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#class-... [2] https://pypi.python.org/pypi/numpydoc [3] http://www.sphinx-doc.org/en/stable/ext/napoleon.html [4] https://bitbucket.org/yt_analysis/yt/pull-requests/2238
On Wed, Jun 15, 2016 at 6:29 PM, Kacper Kowalik xarthisius.kk@gmail.com wrote:
Hi all! As you may know, most of the yt's docstrings are written using so called "numpy-style" [1]. It's not a default Sphinx's format and it requires an extension to parse it. Up till now we've been using numpydoc [2] to handle it. However, numpydoc is a bit buggy and not actively developed. My main issue with numpydoc is that it throws a bazillion of bogus warnings bloating jenkins logs to 100Mb for every docs' build.
There's an alternative extension: napoleon [3] that I'd like to try. The resulting documentation looks a bit different and it may also require a little bit of work to iron out the rough edges. I issued a PR 2238 [4] to show docs with the new look.
I like the new look. It'll certainly be nice to clear these annoying repetitive warning messages that get dumped to our doc build output.
If anyone has issues, we should be able to tweak the appearance by adjusting the CSS in our docs theme.
I'd appreciate your comments. Cheers, Kacper
[1] https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#class-... [2] https://pypi.python.org/pypi/numpydoc [3] http://www.sphinx-doc.org/en/stable/ext/napoleon.html [4] https://bitbucket.org/yt_analysis/yt/pull-requests/2238
yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
Looks cleaner, but you're right there are some rough edges, like how docstring examples are currently handled. Example:
https://tests.yt-project.org/job/yt_docs/929/artifact/sandbox/doc/build/html...
Overall, I like the switch if we can come up with an efficient way of not doing a ton of docstrings corrections into a different format to fix these rough edges.
On Wed, Jun 15, 2016 at 4:48 PM, Nathan Goldbaum nathan12343@gmail.com wrote:
> >
On Wed, Jun 15, 2016 at 6:29 PM, Kacper Kowalik xarthisius.kk@gmail.com wrote:
Hi all! As you may know, most of the yt's docstrings are written using so called "numpy-style" [1]. It's not a default Sphinx's format and it requires an extension to parse it. Up till now we've been using numpydoc [2] to handle it. However, numpydoc is a bit buggy and not actively developed. My main issue with numpydoc is that it throws a bazillion of bogus warnings bloating jenkins logs to 100Mb for every docs' build.
There's an alternative extension: napoleon [3] that I'd like to try. The resulting documentation looks a bit different and it may also require a little bit of work to iron out the rough edges. I issued a PR 2238 [4] to show docs with the new look.
I like the new look. It'll certainly be nice to clear these annoying repetitive warning messages that get dumped to our doc build output.
If anyone has issues, we should be able to tweak the appearance by adjusting the CSS in our docs theme.
I'd appreciate your comments. Cheers, Kacper
[1] https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#class-... [2] https://pypi.python.org/pypi/numpydoc [3] http://www.sphinx-doc.org/en/stable/ext/napoleon.html [4] https://bitbucket.org/yt_analysis/yt/pull-requests/2238
yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
-- Cameron Hummels NSF Postdoctoral Fellow Department of Astronomy California Institute of Technology http://chummels.org
On Wed, Jun 15, 2016 at 7:29 PM, Cameron Hummels chummels@gmail.com wrote:
Looks cleaner, but you're right there are some rough edges, like how docstring examples are currently handled. Example:
https://tests.yt-project.org/job/yt_docs/929/artifact/sandbox/doc/build/html...
FWIW, that doesn't render correctly now either:
http://yt-project.org/docs/dev/reference/api/generated/yt.visualization.volu...
fix:
https://bitbucket.org/yt_analysis/yt/pull-requests/2239
> >
Overall, I like the switch if we can come up with an efficient way of not doing a ton of docstrings corrections into a different format to fix these rough edges.
On Wed, Jun 15, 2016 at 4:48 PM, Nathan Goldbaum nathan12343@gmail.com wrote:
> >
On Wed, Jun 15, 2016 at 6:29 PM, Kacper Kowalik xarthisius.kk@gmail.com wrote:
Hi all! As you may know, most of the yt's docstrings are written using so called "numpy-style" [1]. It's not a default Sphinx's format and it requires an extension to parse it. Up till now we've been using numpydoc [2] to handle it. However, numpydoc is a bit buggy and not actively developed. My main issue with numpydoc is that it throws a bazillion of bogus warnings bloating jenkins logs to 100Mb for every docs' build.
There's an alternative extension: napoleon [3] that I'd like to try. The resulting documentation looks a bit different and it may also require a little bit of work to iron out the rough edges. I issued a PR 2238 [4] to show docs with the new look.
I like the new look. It'll certainly be nice to clear these annoying repetitive warning messages that get dumped to our doc build output.
If anyone has issues, we should be able to tweak the appearance by adjusting the CSS in our docs theme.
I'd appreciate your comments. Cheers, Kacper
[1] https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#class-... [2] https://pypi.python.org/pypi/numpydoc [3] http://www.sphinx-doc.org/en/stable/ext/napoleon.html [4] https://bitbucket.org/yt_analysis/yt/pull-requests/2238
yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
-- Cameron Hummels NSF Postdoctoral Fellow Department of Astronomy California Institute of Technology http://chummels.org
yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
On 06/15/2016 07:29 PM, Cameron Hummels wrote:
Looks cleaner, but you're right there are some rough edges, like how docstring examples are currently handled. Example:
https://tests.yt-project.org/job/yt_docs/929/artifact/sandbox/doc/build/html...
"Example" in this one is actually wrong (header should be marked with ----) Original numpydoc version looks slightly better, but it's more of a coincidence than intended behaviour.
Cheers, Kacper
Overall, I like the switch if we can come up with an efficient way of not doing a ton of docstrings corrections into a different format to fix these rough edges.
On Wed, Jun 15, 2016 at 4:48 PM, Nathan Goldbaum nathan12343@gmail.com wrote:
> >
On Wed, Jun 15, 2016 at 6:29 PM, Kacper Kowalik xarthisius.kk@gmail.com wrote:
Hi all! As you may know, most of the yt's docstrings are written using so called "numpy-style" [1]. It's not a default Sphinx's format and it requires an extension to parse it. Up till now we've been using numpydoc [2] to handle it. However, numpydoc is a bit buggy and not actively developed. My main issue with numpydoc is that it throws a bazillion of bogus warnings bloating jenkins logs to 100Mb for every docs' build.
There's an alternative extension: napoleon [3] that I'd like to try. The resulting documentation looks a bit different and it may also require a little bit of work to iron out the rough edges. I issued a PR 2238 [4] to show docs with the new look.
I like the new look. It'll certainly be nice to clear these annoying repetitive warning messages that get dumped to our doc build output.
If anyone has issues, we should be able to tweak the appearance by adjusting the CSS in our docs theme.
I'd appreciate your comments. Cheers, Kacper
[1] https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#class-... [2] https://pypi.python.org/pypi/numpydoc [3] http://www.sphinx-doc.org/en/stable/ext/napoleon.html [4] https://bitbucket.org/yt_analysis/yt/pull-requests/2238
yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
-
Cameron Hummels -
Kacper Kowalik -
Nathan Goldbaum