Consider migration to MkDocs

[nathanjmcdougall]

I noticed that a docs migration to MkDocs was undertaken for Import Linter. If you would like, I would be happy to have a go at doing that for this repo too.

I think it would be helpful, if only to improve the power of the search functionality. I searched the word "container" to look for a definition, and there was a whole section detailing it, but it didn't come up in search at all. MkDocs has more powerful integrated search in my experience.

As a part of this, all .rst files would be migrated to .md.

[seddonym]

Hi Nathan,

Yes - it's fully my intent to move this over too. Though unfortunately material for mkdocs is now in maintenance mode 😢 so perhaps we should consider another approach (see seddonym/import-linter#316 (comment)).

If you would like to give it a go, feel free - though expect heavy editing as I may want to restructure the docs and am quite opinionated 😄. It might be a better use of time for me to do it, as I did it very recently. Let me know what you think!

[nathanjmcdougall]

unfortunately material for mkdocs is now in maintenance mode

I've experimented with a Zensical migration recently (https://github.com/pypest/pyemu/pull/664/files) and it worked quite well but there is no plugin support so I couldn't use mkdocs-autoapi to generate a full API reference from source code. The Zensical team say they are planning to build a dedicated module to serve this purpose, but it's not there yet.

In general I get the sense that it might be worth waiting at least a couple of months. But it's worth an experiment. The search functionality is really fast & powerful, it lives up to the hype.

If you would like to give it a go, feel free - though expect heavy editing as I may want to restructure the docs and am quite opinionated 😄. It might be a better use of time for me to do it, as I did it very recently. Let me know what you think!

Happy to leave it with you :)