Skip to content

Refactor Docs for Devs and Users #1629

Closed
@waylan

Description

@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.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions