New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Refactor Docs for Devs and Users #1629
Comments
Quoting your comment in #1871 and moving the discussion over 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
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
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. |
Just a note that tomchristie/mkautodoc now exists and can be used to document the API. |
This is the beginings of the work summarized in mkdocs#1629.
During the file reorganization done in #2344, I noted that the theme documentation (now in The document takes the approach that the theme dev would start out by using the |
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):
Getting Started
andInstallation
have been broken out into their own pages. TheHome
page should be a simple introduction with prominate links to the new pages (and perhaps a few others).Note that the
Developer Guide
and theUser Guide
each contain aThemes
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
, theThemes
andPlugins
pages would contain mostly prose regarding their respective topics, while theAPI
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 theutils
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: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.The text was updated successfully, but these errors were encountered: