Skip to content

How to organize documentation#

We will provide some key points from MkDocs User Guide as well as specific notes for Selene documentation.

File layout#

Your documentation source should be written as regular Markdown files (see How to write documentation), and placed in the documentation directory. By default, this directory will be named docs and will exist at the top level of your project, alongside the mkdocs.yml configuration file.

  • Name your files with lower case words separated by - hyphen.
  • Try to pick concise and descriptive filename (coping the whole header is not always a good idea).
  • Tag (label) document type at the end of filename, separated by - (hyphen) as well and before .md extension, sticking to the following recommendations:
    • *-guide.md - like "long-read" with detailed explanation, or article about fundamental things (e.g. quick-start-guide.md);
    • *-howto.md - document type is more focused on solving certain task / issue / problem. A good choice for pages in FAQ section. Please, avoid duplication of "how-to" in the filename (e.g. custom-chrome-profile-howto.md)
    • *-tutorial.md - step by step instruction (e.g. deploy-selenium-grid-tutorial.md);
    • *-example.md - demonstrates usage of Selene. Use Cases section is the right place for these documents (e.g. allure-step-annotations-example.md)

Don't use names which begin with a dot

Files and directories with names which begin with a dot (for example: .foo.md or .bar/baz.md) are ignored by MkDocs, which matches the behavior of most web servers. There is no option to override this behavior.

The file layout you use determines the URLs that are used for the generated HTML pages. Given this layout, pages would be generated for the following URLs:

πŸ“ docs/
β”œβ”€β”€ πŸ“ contribution/
    β”œβ”€β”€ πŸ“„ to-source-code-guide.md
    └── πŸ“„ code-conventions-guide.md
β”œβ”€β”€ πŸ“„ index.md
└── πŸ“„ license.md

/contribution/to-source-code-guide/
/contribution/code-conventions-guide/
/
/license/

The nav configuration setting in your mkdocs.yml file defines which pages are included in the global site navigation menu as well as the structure of that menu.

A minimal navigation configuration could look like this:

nav:
    - Home: 'index.md'
    - About: 'about.md'

Avoid references to page headers in navigation menu

nav:
# ...
    - Release Process: CONTRIBUTING/#release-process  # This is BAD
  • Write navigation section / sub-section / page title and related paths without any quoting
    (maybe it's contr-intuitive, but it's good for YAML syntax highlighting)
  • After completing new document don't forget to update navigation menu in mkdocs.yml file.
    (If it should be there.)
  • Append (insert) link to your page in folder's (section's) index.md file to have a list with all pages in this section.

Selene docs structure#

Selene has following file layout:

  • Can be out-dated here, please look into docs folder or ask project owner where to put new document.
  • Some filenames are not real (for demonstration purpose only).
πŸ“ docs/
β”œβ”€β”€ πŸ“ assets
    β”œβ”€β”€ πŸ“ images
        β”œβ”€β”€ 🎨 logo-icon.png
        └── 🎨 favicon.png
β”œβ”€β”€ πŸ“ contribution/
    β”œβ”€β”€ πŸ“„ code-conventions-guide.md
    β”œβ”€β”€ πŸ“„ how-to-organize-docs-guide.md
    β”œβ”€β”€ πŸ“„ how-to-write-docs-guide.md
    β”œβ”€β”€ πŸ“„ index.md
    β”œβ”€β”€ πŸ“„ release-workflow-guide.md
    β”œβ”€β”€ πŸ“„ to-documentation-guide.md
    └── πŸ“„ to-source-code-guide.md
β”œβ”€β”€ πŸ“ faq/
    β”œβ”€β”€ πŸ“ assets/
        └── 🎨 chrome-driver-window.png
    β”œβ”€β”€ πŸ“„ index.md
    β”œβ”€β”€ πŸ“„ q-tbd-1-howto.md
    └── πŸ“„ custom-chrome-profile-howto.md
β”œβ”€β”€ πŸ“ learn-advanced/
    β”œβ”€β”€ πŸ“ assets/
    β”œβ”€β”€ πŸ“„ index.md
    β”œβ”€β”€ πŸ“„ learn-deeper-1-tutorial.md
    └── πŸ“„ learn-deeper-2-guide.md
β”œβ”€β”€ πŸ“ learn-basics/
    β”œβ”€β”€ πŸ“„ index.md
    β”œβ”€β”€ πŸ“„ quick-start-tutorial.md
    └── πŸ“„ learn-something-tutorial.md
β”œβ”€β”€ πŸ“ use-cases/
    β”œβ”€β”€ πŸ“ assets/
        └── 🎨 my-pic.png
    β”œβ”€β”€ πŸ“„ ex-tbd-1-example.md
    β”œβ”€β”€ πŸ“„ ex-tbd-2-example.md
    └── πŸ“„ index.md
β”œβ”€β”€ πŸ“„ changelog.md
β”œβ”€β”€ πŸ“„ index.md
└── πŸ“„ license.md

Pay attention, that:

  • docs/index.md is almost full include (snippet) of README.md from the project root (except three links at the end). Separate links are required because README is rendered on three place: GitHub, PyPI and Selene documentation website.
  • docs/license.md and docs/changelog.md are full snippets of LICENSE.md and CHANGELOG.md from the project root.
  • contribution/to-source-code-guide.md is snippet of CONTRIBUTING.md from the root (except two links at the end of the page).
  • Images for each section (page type) are located in assets subfolder.
  • Top docs/assets folder contains theme's assets.
  • There is an index.md in each top section.

How to use snippets, please refer to Markdown extension documentation page.

Selene navigation structure#

Initial (might be changed in the future) nav structure (left panel) has following items:

Overview  # -> ./README.md
Learn Basics
    ...
Learn Advanced
    ...
FAQ
    ...
Use Cases
    ...
Contribution
    ...
Changelog
License
Last update: 2023-03-13
Created: 2023-02-27