Mini Crash Course: Documentation using MkDocs
4 min read
Documentation gets out of date quickly because it depends on the code running the software, and code has bugs, and once a bug is fixed or an update is done you need to update your documentation as well. now let us talk about documentation; It is a “material that provides official information or evidence or that serves as a record.”
Documentation is an important part of software engineering. Types of documentation include: Requirements — Statements that identify the attributes, capabilities, characteristics, or qualities of a system. This is the foundation for what will be or has been implemented. Architecture/Design — Overview of software. Includes relations to an environment and construction principles to be used in the design of software components. Technical — Documentation of code, algorithms, interfaces, and APIs. End-user — Manuals for the end-user, system administrators, and support staff. Marketing — How to market the product and analysis of the market demand. Now, let us shift our focus to how we can generate a static site for End-Users using MkDocs. MkDocs “builds completely static HTML sites that you can host on GitHub pages, Amazon S3, or anywhere else you choose”. writing with MkDocs is an amazing experience, maybe it is this way because of the flexibility I enjoy while writing, being able to see a live update of the docs and experiencing it like I’m visiting a web page it’s awesome.
MkDocs is awesome
Beginning with MkDocs
Let me assume you have python installed if not, please do well to get python install on your device by click here. Alright after installing your python the next thing to get up is your “pip” and If you’re using a recent version of Python, the Python package manager, pip, is most likely installed by default. However, you may need to upgrade pip to the lasted version, visit Installing pip to know more. Python and Pip fully checked, is time to install our awesome MkDocs using pip:
Command to install pip.
MkDocs successfully installed, it is time to start our project, create a project and cd into your folder, for example:
project directory created
Moving into our Project folder with the following command:
In our project folder, there’s a single configuration file named mkdocs.yml, and a folder named docs that will contain your documentation source files. Right now the docs folder just contains a single documentation page, named index.md. The index.md have default information that can be edited at any time, now let us start our server via the windows terminal and see how it will display in the browser, starting the server requires you to write command as follows:
Starting your live serve for MkDocs
This triggers an action that builds up your documentation site and provides a local serve code that serves as the URL:
Starting site directory
The highlighted part of the image above is the serving point on which you can access your docs through the browser. first, copy the link past on your browser and you’ll see the default home page is displayed:
Welcome to MkDocs
Open the docs/index.md document in your text editor of choice, change the initial heading to whatever you want and save your changes. Your browser will auto-reload and you should see your updated documentation immediately. Check into mkdocs.yml and change the file you are seeing into a name you want for your site, for example:
My New Docs
Open up your browser and you will see a display like this:
Now add a second page to your documentation and creating an internal link within your site. This home adds a link to your documentation, and creating a page requires you to edit your config file which is in mkdocs.yml like this:
Nav Bar with MkDocs
After editing your configuration file just as I did above, Save your changes and you’ll now see a navigation bar with Home and About items on the left as well as Search, Previous, and Next items on the right.
Theming our documentation
One amazing thing with MkDocs is the ability to add a theme to your docs and thanks to readthedocs community for providing us with an awesome theme. Edit the mkdocs.yml file and add a theme setting:
Adding theme using VS Code
Save your changes, and you’ll see the ReadTheDocs theme being used.
ReadTheDocs Theme Welcome you just publish your first MkDocs documentation site, hope you found this helpful. To read more click on MkDocs