Closed OrkoHunter closed 9 years ago
The changes can be seen here on my fork on readthedocs
Please also look into enabling MathJax on readthedocs so that math expressions marked by single backticks are properly rendered.
I think we will have to use .. autoclass:
instead of .. automodule:
to use the option of disabling documentation of private functions (eg. __init__
).
From http://sphinx-doc.org/ext/autodoc.html#directive-autoclass :
Options and advanced usage
If you want to automatically document members, there’s a members option:
.. automodule:: noodle :members: will document all module members (recursively), and
.. autoclass:: Noodle :members: will document all non-private member functions and properties (that is, those whose name doesn’t start with _).
For modules,
__all__
will be respected when looking for members; the order of the members will also be the order in__all__
.
Please rebase. I changed the docstring of partition()
a little bit (added an extra space). That did not fix the rendering, though. tpwgts
and ubvec
still look wrong.
Okay thanks. I'll rebase after you are done.
I am already done. The change was small enough that I did it directly on GitHub.
According to the napoleon doc, it should support "Attributes" sections. We can disable the auto generated doc for class members and produce the documentation directly from docstrings.
The same doc also says that napoleon requires running sphinx-apidoc
, which seems not to be a replacement for sphinx-build
. The latter is still needed as I read it.
From http://sphinx-doc.org/man/sphinx-apidoc.html :
sphinx-apidoc
generates source files that usesphinx.ext.autodoc
to document all found modules. If any modules have side effects on import, these will be executed byautodoc
whensphinx-build
is run.
I guess we should give a try with sphinx-apidoc
. For that purpose, we have to change the Makefile
. Am I right?
After using Attributes
, I think that the table was bit prettier than how Attributes
lists the parameters.
sphinx-apidoc
is not necessary. It is used to generate nxmetis.rst
and friends. But you already have an (arguably better) handwritten copy.
Putting docstrings beneath enum values works for me, but I do not know how to get rid of the __init__()
functions.
The problem which we are facing is already solved and mentioned in using .. autoclass::. And about the duplication of table, let's keep it as you suggested (keeping docstrings below enum values.)
Please end all docstrings with periods.
Did you publish your changes to your readthedocs fork? I am still seeing the old rendering.
readthedocs automatically builds on every commit. Builds for this branch are published here. http://orkohunter-networkx-metis.readthedocs.org/en/doc-fixes/
Keeping docstrings below enum values is not working on readthedocs.
I just wiped the version on readthedocs and triggered a fresh build.
No changes though.
Well, this is really beyond me. Perhaps we need to ditch autodoc? @hagberg @chebee7i, do you have any suggestions?
The final solution can be rewriting nxmetis.rst
with the docstrings from the module.
So, I believe we drop the use of autodoc
if this is blocking the release.
That makes sense as documentation is the last blocker.
I pushed the changes.
In the toctree, I don't know how does autodoc
generate a table. Efforts like
+----------------+------------------------------------------+
| MetisPType | Partitioning method |
+----------------+------------------------------------------+
and
========== ====================
MetisPType Partitioning method.
========== ====================
render nothing.
This
Partitioning method. <MetisPType>
just replaces the enum with description which is far away from what we want.
Let's proceed with this step by step. Can you move the changes to enums.py
to a separate PR?
After much trial-and-error, this seems to reliably get rid of __init__()
for me:
{{ fullname }}
{{ underline }}
.. currentmodule:: {{ module }}
.. autoclass:: {{ objname }}
{% block attributes %}
{% if attributes %}
.. rubric:: Attributes
.. autosummary::
{% for item in attributes %}
~{{ name }}.{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
in source/_templates/enum.rst
.
:template: enum.rst
to autosummary
in the "Enums" section: .. automodule:: nxmetis.enums
.. autosummary::
:toctree: generated/
+ :template: enum.rst
source/reference/generated
and rebuild.Yes this really removes __init__()
. See the results here
But there are still glitches in repetition of the attributes section. Without the change of the doc strings, there are two tables and after that, there is only one with no content.
Now can you move the changes to nxmetis.rst
and conf.py
to a separate PR so that we can merge them?
This PR is especially for the changes to nxmetis.rst
and conf.py
. I'll remove the extra .rst
files. And I think the duplication of table seems to be resolved by this commit. See this branch.
Please revert the extra .rst
files so that we can merge.
It's okay now.
Fix #48