search

lukasgeiter / mkdocs-awesome-pages-plugin

An MkDocs plugin that simplifies configuring page titles and their order
MIT License
472 stars 36 forks source link

Incorrect order of nav bar entries when awesome-pages is used together with mktheapidocs #17

Closed maxalbert closed 4 years ago

maxalbert commented 4 years ago

This is a revival of #16, but this time with a reproducible example and a proper analysis of the underlying cause. ;)

I should say upfront that I don't think this is necessarily a bug in awesome-pages itself. Rather, it seems to be an unfortunate interaction between awesome-pages and mktheapidocs. However, I'm interested whether you think there is a way this could be handled in awesome-pages, or whether this requires some additional support in MkDocs itself.

I have created a minimal example to reproduce the issue here. As described there, when used on its own awesome-pages works perfectly fine. It picks up the docs/.pages file and correctly arranges the order of the various sections in the nav bar as specified by the arrange key.

However, when the mktheapidocs plugin is activated (by uncommenting the relevant section in mkdocs.yml), it can't find the docs/.pages file any more and therefore the order of the nav bar sections is wrong.

The underlying cause of the bug is that awesome-pages tries to determine the location of the .pages file by determining the common subdirectory of the nav bar sections (via the helper methods _gather_metadata and _common_dirname in the NavigationMeta class).

In our case this location should be the toplevel docs/ folder. However, since mktheapidocs inserts an additional section "Dummy python module" whose underlying files live outside the docs folder (namely, in the in the directory dummy_python_module), awesome-pages gets confused and can't find the relevant .pages file any more.

I'd love to hear your opinions on how this could be resolved. Do you think there is an easy fix in awesome-pages? Or does this require more fundamental support in MkDocs (for example, to have a direct link from a Section instance to the associated directory on disk; or to be able to determine sections that have been dynamically inserted and/or that act like a "symlink" to a different folder, such as the API docs section for "Dummy python module" in this case)?

lukasgeiter commented 4 years ago

Thanks for your analysis and creating a minimal example. As far as I can tell the only solution in this plugin would be to ignore paths outside of the docs_dir when determining the path for a section. This would be similar to how Link items are treated (links to an external site) since those have no path on the disk at all.

I've already created a little proof of concept and it seems to solve this issue. The only thing left to figure out is whether this behavior would be undesirable in some cases (i.e. can this be the default or should there be an option for it).

I would appreciate your thoughts and suggestions on the matter.

maxalbert commented 4 years ago

Many thanks for looking into this, that sounds like a good approach.

I would suggest for the time being to make it the default behaviour (without an explicit configuration option), but to clearly document this behaviour in the README.

You are right that there may be cases where this behaviour is undesirable/insufficient, but I always find it best to wait until there is a concrete example of such a use case, rather than trying to guess what future users may need. If you like you could even add a statement in the README which encourages users to open an issue if the current behaviour is not sufficient for their needs. How does that sound?

lukasgeiter commented 4 years ago

Hey there, so sorry for the long wait. I've just released v2.3.1 which fixes the issue. Just update, and the problem should be resolved. No configuration option or other changes necessary. (although I do recommend you use the new and more powerful nav option instead of the now deprecated arrange - see README for more details)

maxalbert commented 4 years ago

No worries about the wait, I know how life has a tendency to happen. 😅 Plus, this is free and open source software after all that you're voluntarily maintaining, so please never feel bad about developing it at your own pace. ;)

Thanks a lot for the fix! I'm excited to check it out as soon as I get a chance (life is currently happening around here too 😄).