DocsMk

Template and CLI tool to manage a standalone MkDocs documentation.

Including by default:

• Material for MkDocs (Material Design theme).
• Read the Docs integration (ready-to-use configuration).

Usage

Usage: docsmk [COMMAND=serve]

  serve      Run the local server to preview the documentation.
  build      Build the documentation.
  clean      Remove the build directory.
  install    Create a virtualenv and install pip packages.
  upgrade    Upgrade the pip packages.
  uninstall  Remove the virtualenv.
  help       Show this usage.

Installation

Requirements: Python 3, Git, Bash.

In your project folder, execute the following to:

• Copy the DocsMk template (cloning this repository).

git clone git@github.com:ppo/docsmk.git

Then update mkdocs.yml according to your project, and execute the following to:

• Remove the ./docsmk/.git folder.
• Create a Python3 virtualenv (python3 -m venv ./docsmk/.venv).
• Install the required pip packages (see requirements.txt).
• Create the documentation directory (./docs); unless it already exists.

./docsmk/docsmk install

Deployment

Read the Docs

1. Move the .readthedocs.yml file to the root of your repository. No modifications required.
2. Import your project via your dashboard on RTD.
3. That’s it! The building process starts automatically.
   Click on “your documentation is building” to follow its progress.
4. RTD will automatically rebuild the documentation when changes are committed to the repository.

Known Problems

• If you don’t see the projects of an organization in RTD, you’ve to explicitely grant them access to that organization.
  • See Requesting organization approval for OAuth Apps.
  • (information found here)

Documentation

• Importing Your Documentation
• Configuration File
• Incoming Webhooks and Automation

License

This project is licensed under the MIT License. See the LICENSE file for details.