How to work with project documentation

How to work with project documentation

Preface

The existence of detailed documentation is one of the important things for any project. It does not matter whether you use some complex systems or you are a developer of such systems. So, I believe everyone clearly understands for what purposes we need project documentation. In this article we will have a closer look at another thing. I would like to propose an approach which will help you to work with your documents and share them with other users. It consists of three main steps: choosing a format for source files, generating a static site and deployment this site on a git-based hosting service.

To begin with I want to introduce a short observation of some technologies which I will use in the proposed approach. I will focus on Markdown as a base language for writing source files. An example of the static site will be generated by the MkDocs tool. In addition, we will look at the deployment process in details.

How to work with project documentation

Markdown

When you start working with project documentation first you need to decide what format you want to use for source files. Whether it will be html, Markdown, a plain text or something else. In such a situation it’s necessary to understand what you want to see as an end result. A good solution would be using the Markdown language. In such a case you don’t need to make efforts for creating a full html markup. At the same time, there is an ability for converting your documents to the html-format if it’s necessary.

how to work with project documentation-02

Markdown is a lightweight markup language which was specially designed for such purposes. Markdown is often used for creating readme files and project documentation. Below there are some syntax examples. Of course, this is not a complete guide: a full description of the Markdown syntax can be found on the official website.

The most common syntax elements are:

Headings

#Heading                      <h1>Heading</h1>

##Sub-heading                 <h2>Sub-heading</h2>

Text attributes

italic_, *italic*            <em>italic</em>, <em>italic</em>

__bold__, **bold**            <strong>bold</strong>, <strong>bold</strong>

`monospace`                   <code>monospace</code>

Horizontal rule

---                           <hr />

Bullet list

Bullet list:                  <p>Bullet list:</p>

                              <ul>

* one                         <li>one</li>

* two                         <li>two</li>

* three                       <li>three</li>

                              </ul>

Numbered list

Bullet list:                  <p>Numbered list:</p>

                              <ol>

1. one                        <li>one</li>

2. two                        <li>two</li>

3. three                      <li>three</li>

                              </ol>

Link

[Link](http://example.com)    <a href=”http://example.com”>Link</a>

Citations

> Quoted text                 <blockquote>Quoted text</blockquote>

Images

![Alt text](/path/to/img.jpg "Optional title")

In this list, you can find matches between the Markdown syntax elements and a generated html. The characters that are normally seen as special ones in Markdown, can be escaped with a backslash. For example, the sequence "\*" will print the "*" symbol, and won’t be a sign of the beginning of an italic text.

Static site generators

Let’s assume that we already have a set of documents which was written by using the Markdown language. Leave everything as it is if you wrote a simple readme file. However, if your documentation consists of several files and has a complex structure, this is a good reason to compile it as one website. In such a case each markdown file will have an appropriate html file. Also, there will be a front page. Usually, this page contains a common description and some links to the other pages.

Actually, you don’t need to do all the work manually. There are a lot of special tools for building static websites (Jekyll, Hugo, GitBook, MkDocs and so on). Here you can find quite a big rating of the most popular projects. In my example, I will use MkDocs. Thus for a better understanding, I would like to make a short review of its functionality.

MkDocs

MkDocs is a popular static site generator that is aimed at building project documentation. It uses source files which are written in Markdown. To specify a project structure you need to edit yaml configuration file (mkdocs.yml). Below there is an example of such a file:

   site_name: MkLorum

   pages:

       - Home: index.md

       - Articles:

           - Article 1: articles/article-1.md

           - Article 2: articles/article-2.md

       - About: about.md

   theme: readthedocs

It includes a site name (site_name parameter), a structure of pages (pages parameter) with navigation links and a theme (theme parameter) that will be used for a stylization of the whole site. The navigation links for pages can have a nested structure. It helps to group pages by the necessary categories. Besides, for MkDocs there is a good collection of the built-in and 3rd party themes which helps to customize your site.

For getting started it’s necessary to create a new project.

mkdocs new my-project

cd my-project

By default, the new project has the following structure:

how to work with project documentation-03

There is a configuration file named mkdocs.yml and a docs folder with an index.md file. This file contains some code examples. It will help you to feel simplicity and flexibility of the Markdown language. Especially if you work with this language for the first time.

MkDocs comes with a built-in dev-server. This allows you to see results of work locally. In other words, you don’t need to deploy your site somewhere to check if everything works correctly. To launch the dev-server it’s necessary to go to the root project directory (where the mkdocs.yml file is located) and run the mkdocs serve command.

~/my-project$ mkdocs serve

  INFO    -  Building documentation...

  [I 170311 18:04:57 server:271] Serving on http://127.0.0.1:8000

   [I 170311 18:04:57 handlers:58] Start watching changes

Now it should be possible to open your site in a web browser by typing this url - http://127.0.0.1:8000. If you set up everything correctly, you will see something like this (an appearance depends on a version of mkdocs and on the chosen theme):

how to work with project documentation-04

Based on the set of existing documents, you can build the final static site (mkdocs build command). All the necessary files will be stored into a site folder.

~/my-project$ mkdocs build

  INFO    -  Building documentation to directory: ~/my-project/site

So, it remains to solve only one problem - how to share your results with other users?

Deployment

Actually, there are a lot of options how you can handle this: whether it’s your local server, a cloud hosting or something else. Everything depends on what goals you want to achieve.

Let’s look at the situation when you have an open-source project and project documentation must be accessible for everybody. A good option, in this case, is using some free services for hosting static websites. Great examples of such services are GitHub and GitLab. In addition to the version control system, you will get a workflow to handle your documentation, an ability to use a continuous integration and other useful things. In order not to be unfounded next I will provide you an example of configuring such an environment on GitLab.

GitLab Pages

GitLab supports many tools for generating static sites. Here you can find a lot of useful examples. It also includes an example of the MkDocs site that supports GitLab Continuous Integration.

Let’s fork this test site. If you have no plans to contribute back to an upstream project, please go to your project’s settings and remove the forking relationship.

Next, you need to make sure that shared Runners are enabled for your project (Settings->”CI/CD Pipelines” then click on “Enable shared Runners”). It will bring you several advantages. Your build will run on a separate Virtual Machine which uses Docker containers. This approach minimizes a probability of security issues because containers have an isolated architecture. Shared Runners are activated for new projects. So, you probably don’t need to do anything to activate them.

how to work with project documentation-05

By default, your project page will be available at https://username.gitlab.io/projectname. This configuration is called a Project Page. It’s possible not to use the project name part in url. To do this go to the project settings page (click on the “Gear” icon, then on the “Edit Project” link) and rename the project to username.gitlab.io. Now your build is available at https://username.gitlab.io/. This configuration is called a user Page.

how to work with project documentation-06

In addition to these default configurations, you can set up using custom domains and ssl/tls certificates.

GitLab CI

Don’t worry if any attempts to open the project/user page returns a 404-error. It happens because you currently don’t have a build for the project. To trigger a building process it’s necessary to commit and push something to the project repository. By the way, you can edit files directly in GitLab from your browser.

The build process will begin as soon as the changes are added. A set of actions that will be executed during the building process depends on the specified settings. GitLab Runner will get these settings from a yaml-file named .gitlab-ci.yml. Let’s look at the structure of this file.

 image: python:alpine


   before_script:

     - pip install mkdocs

     ## Add your custom theme if not inside a theme_dir

     ## (https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes)

     # - pip install mkdocs-material


   pages:

     script:

     - mkdocs build

     - mv site public

   artifacts:

     paths:

     - public

   only:

   - master

In this case, GitLab Runner launches a container which is based on a Docker image with Python (it’s required for MkDocs). Before doing any manipulations with project’s files it installs the mkdocs package. Next, as usual, it runs the mkdocs build command and renames a “site” folder to “public”. Keep in mind that Runner will track changes only from the master branch. You can customize the .gitlab-ci.yml file by adding whatever you want. Besides, there is a possibility to check your settings (CI Lint tool) before adding them to the project.

Status for each build process is available directly on the GitLab site (Pipelines->Jobs, then click on the status for the selected job). Sometimes it may be useful to check this in order to find any problems with deployment. The “passed” status means that the building process was successful. Now you can enjoy your new site for project documentation!

how to work with project documentation-07

Conclusion

In this article, I’ve reviewed the approach to working with project documentation. It includes choosing a format of source files, generating a static site and deployment of this site on a git-based hosting service. This approach will help you to choose the necessary tools for writing and deploying your documentation in case you want to share it with everybody. Let’s list some key moments:

  • Format of source files
    • I’ve focused on Markdown as a base language for writing source files.
    • Markdown allows to use an easy-to-read plain text format, but at the same time, there is an ability to convert your files to html.
  • Static site generators
    • If your documentation consists of several files and has a complex structure, this is a good reason to compile it as one website by using some static site generator.
    • There are a lot of special tools for building static websites (Jekyll, Hugo, GitBook, MkDocs and so on). The tool you choose depends on your needs.
  • Deployment
    • If you have an open-source project and project documentation must be available for everybody, it’s a good option to use some git-based hosting services, such as GitHub or GitLab.

That’s all that I wanted to tell you within this article. Hope the described approach and the provided examples will be useful for you.

You might also like