Flatten documentation hierarchy

[mrocklin]

Fixes #89

[mrocklin]

Some additional things that would be nice to fix (but I'm not sure how):

1. Flatten the API docs to require fewer clicks to get to a function of interest. Currently the API page has a single option that you have to click on. This seems silly, but is perhaps necessary for the machinery we're using now?
2. Remove scrollbars from code blocks

[hameerabbasi]

arithmentic -> arithmetic

[hameerabbasi]

This probably has a link to the GitHub page that might need to be changed.

[hameerabbasi]

This might also have a GitHub page link.

[hameerabbasi]

Some feedback. Also see my comments over in #89.

[hameerabbasi]

1 can be fixed by moving generated/sparse.rst to api.rst, and redoing the headings. 2, I'm not so sure about.

[hameerabbasi]

Comment.

[hameerabbasi]

This should be moved below the sys.path.insert, otherwise it won't work. RTD runs Sphinx from the docs directory.

[hameerabbasi]

This gets a +1 from me, but you should still do #90 (comment) if possible.

[mrocklin]

Thoughts on how to change the title of the page and TOC line from sparse to API? I can change the file, but presumably that file gets auto-generated and so the change would be lost.

[hameerabbasi]

I apologize in advance for stating things you may already know here.

Actually, it doesn't. It only gets auto-generated if it's deleted. If it's not deleted, the change sticks. That's a feature so we can modify auto-generated pages.

Also, it only gets auto-generated if there's an autosummary directive somewhere upstream. We would be changing the main autosummary directive from the modules page to the sparse page.

I would suggest the following:

• Delete api.rst
• Move generated/sparse.rst -> api.rst
• Change the heading.
• Add a toctree directive of generated like the current api.rst.
• Add :ref: roles in the flattened document. (see below for tl;dr).
• Modify generated/sparse.COO.rst to match the new labels.

You can also do this for inter-links:

.. _my-label:

Some section heading
----------------------


# Somewhere else, maybe even in another file entirely!
:ref:`my-label` # Automatic title for link text!
:ref:`A link <my-label>` # Custom link text

You may need to delete your build directory, otherwise it doesn't fully update the TOC on every page, and you will only see a fraction of the warnings (such as the ones that should have happened for missing cross-links when you changed the documentation structure). RTD does this for us.

If this is all too much for you, I can take over and push a commit or two. If not, it's a great learning experience!

[hameerabbasi]

If you want to put the COO and DOK classes on the main API page, copy over their contents and get rid of the classes part in sparse.rst

[hameerabbasi]

Alternatively, you could just not move them and rename sparse.rst to api.rst and do the changes there. In this case, you don't need a :toctree: directive.

[mrocklin]

Rebased on master. Merging this soon if there are no objections.

[hameerabbasi]

Minor comment... The original api.rst should be deleted.

[hameerabbasi]

And there's still the problem of missing/broken cross references in generated/sparse.COO.rst. :-) I can do that if you have issues.

[mrocklin]

And there's still the problem of missing/broken cross references in generated/sparse.COO.rst. :-) I can do that if you have issues.

If you wanted to handle that that would be welcome. It might also be useful to have the autosummary references come before the autoclass and large docstring. That way people can more easily see the options they have on this page.

[hameerabbasi]

True. I'm a bit busy today, I might not be responsive. I'll handle it tomorrow, if you're okay with that.

[mrocklin]

No rush on my end. I wanted to get this in to avoid having to rebase further and handle conflicts with other PRs that touch documentation. But if you're busy then those are unlikely to arise anyway :)