Documentation using MkDocs
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.”
- 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.
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:
MkDocs successfully installed, it is time to start our project, create a project and cd into your folder, for example:
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 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:
This triggers an action that builds up your documentation site and provides a local serve code that serves as the URL:
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:
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:
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](about.md) adds a link to your documentation, and creating a page requires you to edit your config file which is in
mkdocs.yml like this:
After editing your configuration file just as I did above, Save your changes and you’ll now see a navigation bar with
About items on the left as well as
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
Save your changes, and you’ll see the ReadTheDocs theme being used.
Welcome you just publish your first MkDocs documentation site, hope you found this helpful.
To read more click on MkDocs