Api docs patch #7289
Api docs patch #7289
Conversation
Sphinx's autodoc (more specifically, napoleon extension) only allows a fixed set of section headers in NumPy style docstrings, and causes an error, "unexpected section title", when building docs. This commit introduces a "Notes" section, relegates headers to regular text, and adds double blank lines before. IMHO this produces a nice compromise for readability in docstrings, command line help, and online documentation.
Replaces single quotes with reST double backticks.
mslw
added
the
semver-documentation
Codecov ReportBase: 88.73% // Head: 90.66% // Increases project coverage by
Additional details and impacted files@@ Coverage Diff @@
## maint #7289 +/- ##
==========================================
+ Coverage 88.73% 90.66% +1.93%
==========================================
Files 326 326
Lines 44429 44415 -14
Branches 5919 5919
==========================================
+ Hits 39422 40270 +848
+ Misses 4992 4130 -862
Partials 15 15
Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here. ☔ View full report at Codecov. |
| api.export_to_figshare | ||
| api.no_annex | ||
| api.shell_completion |
There was a problem hiding this comment.
I know that would be much to ask but since it seems to be "common" to forget to include them in modref, a unittest could be added to https://github.com/datalad/datalad/blob/HEAD/datalad/tests/test_api.py#L81 or around to alert when interface is not present in modref.rst if it would find it present?
not sure though if wouldn't interfer with the cases of extensions. so consider as a really weak wishlist
There was a problem hiding this comment.
Thanks for pointing out that test, I wasn't aware of it. So the added test would need to parse modref.rst?
With extensions though - if they are listed in interface groups, then I suppose the outcome would depend on what is installed in test environment (which doesn't have to be CI). Although taking a random virtualenv and quickly checking, that might not be the case.
I guess that could be done, question is whether it should be done ;)
Can't use actual ReST subsections in docs without crashing docs autogeneration unless the headings are declared in Sphinx configuration - see commit 6956042 for more details (and less formatting). Suggested-by: Yaroslav Halchenko <debian@onerussian.com>
|
I don't see myself working on a test that compares the ReST document to the actual API in the coming days due to other backlogs, and since @yarikoptic sees it as "a really weak wishlist", I'd like to propose this PR as is. |
|
PR released in |
This PR adds
create_sibling_ria,foreach_dataset,export_archive_ora, andshell_completionto the table of contents in the Python module reference, therefore including them in the html documentation.This required a change to section headings in the
create_sibling_riadocstring, because sphinx napoleon extension only allows a set of predefined headings (custom ones can be added, but I thought reformatting makes more sense). I also used the opportunity to change single quotes into double backticks in said docstring, but compared to headings this isn't necessary for the docbuild.Details in commit messages. Closes #7288