Refactor Docs for Devs and Users

[waylan]

The documentation could be reorganized to better separate the info for users from the info for developers (themes and plugins). I'm thinking the Nav might look something like this (actual page titles and order subject to change):

- Home
- User Guide:
    - Getting Started
    - Installation
    - File Layout
    - Writing Markdown
    - Configuration
    - Themes
- Developer Guide:
    - Themes
    - Plugins
    - API
- About:
    - Release Notes
    - Contributing
    - License

Getting Started and Installation have been broken out into their own pages. The Home page should be a simple introduction with prominate links to the new pages (and perhaps a few others).

Note that the Developer Guide and the User Guide each contain a Themes page. Each would contain theme related documentation specific to the needs of theme develpers and users respectively. Currently the two are mixed with pieces of each intermingled, which makes it hard for devs to find what they need and can be overwhelming for users.

In the Developer Guide, the Themes and Plugins pages would contain mostly prose regarding their respective topics, while the API page would document the various classes, methods, and functions in the MkDocs' code base which plugin devs might need to use. For example, plugins can define their own config, but we currently have no documentation about the config classes and how to use them. We also define page and nav objects for theme devs (attributes which might be called from a template), but not for plugin devs (all public attributes and methods of the class). Many of the utils functions could be useful to plugin devs as well.

Much of the work consists simply of rearranging the existing documentation with minor edits to make the text fit in it's new context. However, the API is currently non-existent. I see two possible paths:

1. Author the documentation from stratch in Markdown.
2. Build a plugin which extracts documentation from the source code.

Option two would certainly be more userful long term (and it provides a new feature for other users), but it would be more work as much of the source code has very limited documentation in the comments.

Whichever way we go, the rest of the work could be started now. The API can always be added later.

[squidfunk]

Quoting your comment in #1871 and moving the discussion over here:

I suspect that proposed change would help immensely with the MkDocs vs. theme problem. If only I had the time to do the work... Please feel free to provide any feedback on the idea in that issue rather than here.

The proposed changes may be a good start reducing any potential template-related issues that are opened here and related to non-default templates like for example mkdocs-material. I haven't checked how often this happens though.

Also, we could ask reporters to confirm that the issue is unique to a specific theme. I know you recently created an 'issue template.' I'm not sure if that is included or not. I could probably do the same. Although, I'm not particularly fond of those sorts of templates (I feel like they box me in when I'm trying to report an issue).

The reason why I did this is that quite recently there were a lot of one-line issues, some of them with questions that are either clearly answered in the docs or questions that are related to customizations for which I don't provide support for obvious reasons.

My biggest problem is that people think that mkdocs-materialis actually mkdocs. For the bug template I included a checklist that the user should go through which has the following requirements:

• ... the documentation does not mention anything about my problem
• ... the problem doesn't occur with the default MkDocs template
• ... the problem is not in any of my customizations (CSS, JS, template)
• ... there are no open or closed issues that are related to my problem

What happens? Most people just delete that stuff and go with LOL MY DOCS DON'T WORK HELP ME NOW KTHX. Neither a technical description of the bug, nor a reproducible case.

I agree that the template may be a little uncomfortable and box the reporter, but it's our spare time in which we answer those issues and help other people for no compensation whatsoever, so I really think it's absolutely fair to request a thoroughly researched issue which is easy to reproduce. I'm really sick of this.

[waylan]

Just a note that tomchristie/mkautodoc now exists and can be used to document the API.

[waylan]

During the file reorganization done in #2344, I noted that the theme documentation (now in dev-guide-theme.md) needs a refactor of its own. A lot has been added to that document over the years and it is a confusing mess (see this comment and the few that follow for an example).

The document takes the approach that the theme dev would start out by using the theme.custom_dir and then later move to a standalone Python package. However, in most cases, I expect third party themes start out as separate Python packages, so we should document creating them from that perspective. Any custom_dir specific content should be moved to the user-guide as that feature would be used exclusively by users. That said, we do want to include some comments about the custom_dir so that theme devs remember to include support for it in their themes.