Technical Documentation

Introduction: This article explains about writing technical documentation using Mkdocs, installation, update and deployment on production.

Installation: Follow these steps to setup Mkdocs on your local machine and run its dev server.

Install Python by downloading an appropriate installer for your operating system from python.org.**

Install mkdocs package using the following command pip install mkdocs
You should now have the mkdocs command installed on your system. Run mkdocs --version to check that everything worked okay.
Use the following command to start the server mkdocs serve --dev-addr=127.0.0.1:8080.

Note*: The `--dev-addr` switch is optional and need only be used to change the port on which the server is run.*

The dev server also supports auto-reloading, and will rebuild your documentation whenever anything in the configuration file, documentation directory, or theme directory changes

Adding or updating documents: Follow these steps to make create new documents or update existing ones.

Setup a new repository on your version control(e.g. github, gitlab etc…).
Every technical documents must be written in markdown format (.md) and added to the docs folder.
Follow the appropriate directory structure to store documents.

4. Update the mkdocs.yml file to add reference to your new page.

5. Start the dev server to make sure everything compiles, and the document is properly formatted and linked.

6. Create a merge request for your changes.

Deployment via Docker: Setup the Jenkins pipeline so that whenever the merge request has been accepted deploy it on server so that everyone can access the documentation as html.

.htpasswd

root:$passw0rd

Shell Script

 chmod a+x $WORKSPACE  
 mkdocs build

DockerFile

FROM nginx  

COPY nginx.conf /etc/nginx/nginx.conf  
COPY .htpasswd /etc/nginx/.htpasswd  

WORKDIR /usr/share/nginx/html  
COPY site/ .

nginx.conf

worker\_processes  1;  

events {  
    worker\_connections  1024;  
}  

http {  
    server {  
        listen 80;  
        server\_name  localhost;  

    auth\_basic           "Restricted area";  
    auth\_basic\_user\_file /etc/nginx/.htpasswd;  

        root   /usr/share/nginx/html;  
        index  index.html index.htm;  
        include /etc/nginx/mime.types;  

        location / {  
            try\_files $uri $uri/ /index.html;  
        }  
    }  
}

Customization:: To customize more features like icon, theme etc… follow their official guideline. https://www.mkdocs.org/getting-started/#getting-started-with-mkdocs

Technical Documentation via MkDocs