search

mli / new-docs

https://beta.mxnet.io/
13 stars 17 forks source link

reference block methods for detail links #51

Closed aaronmarkham closed 5 years ago

aaronmarkham commented 5 years ago

In HybridBlock, many of the methods do not show a link, so I set these to display Block instead, where a link with detailed usage is available.

I do wonder if there's a way to show this difference - the fact that some methods are inherited and some are extended.

Note: having the functions link to detailed descriptions is very important, however, at this moment there are over 100k warnings or errors from Sphinx on how the docs are generated (not related to this PR). The site won't make it to production in this state, and it makes it really hard to see if we're doing things right when making changes like in this PR.

aaronmarkham commented 5 years ago

Ping.... I need a review on this before moving forward on anything similar in the API folder.

aaronmarkham commented 5 years ago

@mli @astonzhang I need feedback on this PR before proceeding. Thank you!

astonzhang commented 5 years ago

As we discussed offline, changes like this are ad-hoc. Is there any other way to address the problem?

aaronmarkham commented 5 years ago

As we discussed offline, changes like this are ad-hoc. Is there any other way to address the problem?

I don't know. It seems like trial and error, with mostly error. Should I rip out anything that causes an error, then create issues for each so that someone that knows how/why it was implemented the way it was can go in and fix the docs generation?

astonzhang commented 5 years ago

@mli Could you offer some inputs here?

mli commented 5 years ago

http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html has a solution for it.

For classes and exceptions, members inherited from base classes will be left out when documenting all members, unless you give the inherited-members flag option, in addition to members:

.. autoclass:: Noodle
   :members:
   :inherited-members:

please use the official recommended way to add links.