Skip to content

Improving docs

Docs are powered by MKDocs

The documentation of refreshVersions is published on a website accessible via this url: https://splitties.github.io/refreshVersions.

It is generated with MKDocs from Markdown files. The variant of Markdown used in MKDocs has useful additional features that we use: - “Variables” interpolation, useful for long urls repeated in the doc. - Automatic generation of table of contents based on headings.

Where is the doc source

A bunch of things are defined in the mkdocs.yml file (located at the root of the repo):

  • The structure of the documentation website is under the nav key.
  • Under the extra key, we have common text snippets (example usage: {{link.github}})
  • Website metadata is defined at the top of the file (you probably don’t need to touch it)
  • Theme and MKDocs configuration

The content of the documentation itself is in the docs directory where you can find Markdown files and images in the img directory.

Edit the doc

Before starting any work, create a branch in your fork that is based on the release branch.

Please, avoid non-improvements such as adding typos, or spelling errors.

Also, try to keep the language simple, non-ambiguous, and explicit enough, so all of our users can understand it. 🙏

View your changes

Run one of the following commands, to ensure you have the tools to build the website locally:

  • pip3 install -r docs/requirements.txt
  • pip install -r docs/requirements.txt

Note: on Linux and macOS, pip3 is most likely already installed. On Windows, you might want to install anaconda/Python to get it.

Start the local server using the mkdocs serve command.

You’ll quickly see a link appear in the console to view it in your default browser.

Any saved changes will refresh the page automatically if the right one is open in the browser.

Once you’re done, you can close the tab, and quit the local server (ctrl + C).

Submit your changes

Once you’re done, please commit your changes with a clear title and message that mentions what changed in simple terms, then submit the pull request on GitHub.