Some documentation changes

[OrkoHunter]

Fix #48

• Corrected the reference link
• Added MathJax extension

[OrkoHunter]

The changes can be seen here on my fork on readthedocs

[ysitu]

Please also look into enabling MathJax on readthedocs so that math expressions marked by single backticks are properly rendered.

[OrkoHunter]

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__.

[ysitu]

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.

[OrkoHunter]

Okay thanks. I'll rebase after you are done.

[ysitu]

I am already done. The change was small enough that I did it directly on GitHub.

[ysitu]

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.

[ysitu]

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.

[OrkoHunter]

From http://sphinx-doc.org/man/sphinx-apidoc.html :

sphinx-apidoc generates source files that use sphinx.ext.autodoc to document all found modules. If any modules have side effects on import, these will be executed by autodoc when sphinx-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?

[OrkoHunter]

After using Attributes, I think that the table was bit prettier than how Attributes lists the parameters.

[ysitu]

sphinx-apidoc is not necessary. It is used to generate nxmetis.rst and friends. But you already have an (arguably better) handwritten copy.

[ysitu]

Putting docstrings beneath enum values works for me, but I do not know how to get rid of the __init__() functions.

[OrkoHunter]

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.)

[ysitu]

Please end all docstrings with periods.

[ysitu]

Did you publish your changes to your readthedocs fork? I am still seeing the old rendering.

[OrkoHunter]

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.

[OrkoHunter]

I just wiped the version on readthedocs and triggered a fresh build.

[OrkoHunter]

No changes though.

[ysitu]

Well, this is really beyond me. Perhaps we need to ditch autodoc? @hagberg @chebee7i, do you have any suggestions?

[OrkoHunter]

The final solution can be rewriting nxmetis.rst with the docstrings from the module.

[OrkoHunter]

So, I believe we drop the use of autodoc if this is blocking the release.

[ysitu]

That makes sense as documentation is the last blocker.

[OrkoHunter]

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.

[OrkoHunter]

Please see http://orkohunter-networkx-metis.readthedocs.org/en/doc-fixes/

[ysitu]

Let's proceed with this step by step. Can you move the changes to enums.py to a separate PR?

[ysitu]

After much trial-and-error, this seems to reliably get rid of __init__() for me:

• Put

{{ 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.

• Use the template by adding :template: enum.rst to autosummary in the "Enums" section:

 .. automodule:: nxmetis.enums
 .. autosummary::
    :toctree: generated/
+   :template: enum.rst

• Remove source/reference/generated and rebuild.

[OrkoHunter]

50

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.

[ysitu]

Now can you move the changes to nxmetis.rst and conf.py to a separate PR so that we can merge them?

[OrkoHunter]

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.

[ysitu]

Please revert the extra .rst files so that we can merge.

[OrkoHunter]

It's okay now.