support hide metadata and update docs

[2bndy5]

This resolves #39 and closes #37

I updated the docs to guide users on how to hide a certain page's ToC and navigation menu. While I was updating customization.rst, I also added a hint about sphinx auto-implementing navigation.indexes feature from mkdocs-material.

[jbms]

I also noticed that tocdepth is not actually respected by nav_adapt.py, other than handling the special case of tocdepth == 0.

Possibly we could support :hide: toc as well for consistency with mkdocs and since it is clearer than having to specify tocdepth.

[jbms]

I guess one challenge with :hide: as a field element is that it seems that sphinx creates a dictionary --- is there a way to support multiple :hide: metadata values?

[2bndy5]

is there a way to support multiple :hide: metadata values?

This is why I chose to keep the implemented tocdepth metadata. I suppose we could do

hide_list = meta.get("hide").split(",")
hide_list = [hide.strip() for hide in hide_list]
if "navigation" in hide_list:
    # ...
if "toc" in hide_list:
    # ...

[jbms]

Actually I think we should go with something like :hide-navigation: rather than :hide: navigation --- that way we are more consistent with how these document metadata fields are normally treated (as key-value assignments).

[2bndy5]

Would you like to preserve the tocdepth option for backward compatibility? Or do you consider it broken enough to get rid of it?

[2bndy5]

metadata fields are normally treated (as key-value assignments).

So what value do you propose? A bool? Or does sphinx use a default value in case none is specified?

[jbms]

I think they are just parsed as strings, but for bool flags the convention seems to be to just leave the value blank:

https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html#special-metadata-fields

So just:

:hide-navigation:

As far as tocdepth --- thinking about it more, I think we should just keep using tocdepth for this purpose, rather than introducing a new :hide-toc: field. At some point we should actually make non-zero values of tocdepth have their proper effect, but for now it seems reasonable to leave it as is.

I think currently, on the master document only the toc depth is limited to 2, and on all other pages the toc depth is unlimited. This difference is due to the fact that nav_adapt.py uses different logic in those two cases for obtaining the local toc.

[2bndy5]

I can implement both hide-toc while preserving tocdepth. In testing the new metadata idea, the users would have to specify

:hide-naviagation: anyValue

otherwise, no value has no effect.

.. this has no effect
:hide-naviagation:

[2bndy5]

NM, I got it to work if the metadata is specified at all. If it isn't there, then the feature is not enabled for that page.

[2bndy5]

I'm going forward with the hide-toc idea because it better matches mkdocs-material convention (& its more descriptive). People migrating from mkdocs to sphinx may get confused about the toctree directive's option maxdepth. To be clear, :tocdepth: 0 will still work (just like hide-toc).

[2bndy5]

woah! I just tried switching the direction to rtl, and there's a bunch of problems... It would seem that the side nav menus don't swap sides despite the direction specified, but I think there's more than a few bugs happening here.

I'll remove the "( or XXX side in rtd languages direction)" from the last commit's change to docs. We can work that out when the direction is fixed.

[jbms]

Thanks!