Confusing usage, please document

[petri]

Please explain in more detail what this page configuration syntax means?

   ['api/autodoc:mkdocs', 'API', 'mkdocs']

It is self-explanatory that "API" is some kind of page title or such, and that "mkdocs" refers to the Python module name. But, the "api/autodoc:mkdocs" syntax?

When I tried the above, I got a File Not Found on docs/api/autodoc:mkdocs . Creating the file (with no content) only makes things worse, resulting in a Python traceback:

IOError: [Errno 20] Not a directory: '/var/folders/6w/0014ssc53ys6ym6j8ttn98m40000gn/T/tmpad4DDn/api/autodoc:mkdocs/index.html'

What is the syntax supposed to mean, and are we supposed to create some files or directories ourselves or is this a bug?

[d0ugal]

This package requires a forked version of MkDocs, if you are not using that - it wont work.

[erichulser]

Hi petri -- as d0ugal mentioned -- this code requires a very specific fork of mkdocs to work. If you would like to try it, that fork is here: https://github.com/ProjexSoftware/mkdocs and must be cloned and manually setup.

There is no intention to maintain that fork, it was created to implement an proposed extension system to mkdocs and is now quite old compared to the main development branch. At this point, I'm on a holding pattern until the owners/developers of mkdocs itself are ready to look into an extension system, at which point this project will update to reflect that implementation.

That being said, we're using this fork & extension in our development & documentation and are simply keeping a local version of mkdocs until the main project is ready.

[erichulser]

I have also updated the documentation on the README page for this project to reflect that requirement.

[erichulser]

Hi petri -- I just re-read through the documentation and realized that it is a bit confusing. I have also updated the usage documentation so hopefully it makes a bit more sense now as well.

[petri]

Thanks Eric! Here's +1 hoping for MkDocs to adopt an extension system you could work with...

[d0ugal]

We will, it is just a matter or the time and effort and priorities etc. :)

[nsheff]

Hi, sorry to resurrect a 3 year old thread -- I've been trying to figure out how to use mkdocs with autodoc and came across this old conversation. I see that there is now a plugins system for mkdocs (https://www.mkdocs.org/user-guide/plugins/), but I was wondering if there are any plans underway to run either this autodoc system or some other with the more up-to-date mkdocs branch.