Docs-as-code in action: Documenting a Python library.

Documentation is a crucial resource for helping your target audience understand how to use your product effectively. High-quality documentation not only communicates the core problem your product solves but also empowers users to achieve their desired outcomes seamlessly.

The same holds true for open-source libraries and packages. Clear and accessible documentation is essential for guiding developers on how to integrate these tools into their projects successfully.

In recent years, the Docs-as-Code (DaC) approach to documentation has gained significant popularity. This method treats documentation as a fundamental part of the software development lifecycle by using the same tools and processes developers rely on for code.

This method is widely accepted because it promotes consistent, version-controlled, and easily maintainable documentation that evolves alongside the product.

What is Docs-as-code?

In simple terms, DaC is a method that involves handling and maintaining documentation as you would do to your code.

A typical software development life cycle involves 7 stages which include the following:

1. Planning
2. Gathering Requirements and Analysis
3. Design
4. Coding and implementation
5. Code testing
6. Code deployment
7. Code maintenance

Therefore, DaC is a new approach that ensures documentation goes through the same stages. This keeps the documentation versioned and up to date with software changes.

Deployment without DaC

Deployment with DaC

While this guide may not go in-depth into the theoretical aspect of DaC, you can explore the Beginner’s guide to Docs-as-code article which explains the concept behind DaC in detail.

Project Overview

This guide involves the practical implementation of DaC with Python. You will learn how to document an open-source Python library using Mintlify.

Mintlify is a static site generator and documentation site used for public-facing documentation. It is easy to maintain and use for various documentation needs such as developer documentation, API documentation, etc. It also works well with the DaC methodology.

This tutorial is a sequel to an existing tutorial on how to build and deploy a Python library. Using the DaC methodology, you'll learn how to document the Python library developed referenced tutorial.

It is recommended that you complete the previous tutorial before you continue. However, you can proceed if you have an existing project to use for this tutorial.

Project requirements

A basic knowledge of Git and GitHub, how to create a Github repository and how to push your code to GitHub us required. You also need the following tools for this tutorial:

• Mintlify account: You need an active Mintlify account to create documentation (steps will be provided in the guide).
• Node.js: You will need Node.js version 18 and above to install Mintlify and edit your documentation locally.

Setup a Mintlify documentation

Follow the steps below to setup a documentation using Mintlify:

1. Create an account on Mintlify

2. Setup your Mintlify account:
A verification link will be sent to your mail. This link will redirect you to the page below:

3. Sign in with Github:
The first step requires you to sign in with your Github account.

4. Create a GitHub repository (repo) for your documentation:
The next step requires you to install and authorize the Mintlify app on your Github account. This allows Mintlify to automatically create a repo for your docs

5. Access your documentation repo:
The previous step creates a new docs repo for your documentation. Check your GitHub repositories for a new docs repo

Add the documentation to your project

The next step is to clone the docs repo to your local environment and add it to an existing project such as a developer tool, open-source package, etc. If you already completed the previous tutorial, your project will be exchangeLibrary.

Follow the steps below to add the documentation to your project:

1. Open the terminal and clone the docs repository with the command below:

git clone https://github.com/<your github username>/docs 

2. Copy the cloned docs folder to your project.

3. Open the project in a code editor.

Your project file structure should now look like this:

Preview documentation locally

Mintlify allows you to preview your documentation locally before publishing it. Follow the steps below to set it up:
1. Open your project in the terminal
2. Run the command below to install Mintlify globally:

git clone https://github.com/<your github username>/docs 

3. Switch to the docs folder in your project:

npm i -g mintlify

4. Start a mintlify server with the command below:

cd docs

You should see a message like the one below in your terminal:

Open the URL to preview the documentation locally. The content of your documentation will be the Mintlify starter doc template. This will change when you start editing your documentation.

Writing the documentation

A Mintlify documentation is powered by the mint.json file. This file contains the color scheme, pagination, and navigation settings for the documentation. You can find it in the project’s docs folder.

Also, documentation files in Mintlify are written in .mdx. It is almost similar to markdown(.md) except that it allows special tags and symbols.

In this section, you will learn how to edit your documentation settings in the mint.json file, and how to add texts and special components to your documentation.

Edit documentation settings

The mint.json file is a JSON object made up of color schemes, pagination, navigation settings, etc. for your documentation. Below is a list of available settings and what they mean:

1. Color scheme and appearance:
This section is used to beautify and enhance your documentation appearance. It is used to change the logo (for both light and dark mode), favicon, title, and color scheme for the documentation. It starts from the $schema key to the colors key as seen below:

mintlify dev

2. Navigation links and CTA button:
This section is used for setting up navigation links and buttons at the top of the documentation page. Below is an example of a navigation link and button:

The code below sets up the navigation links and a CTA button for your Mintlify documentation:

  "$schema": "https://mintlify.com/schema.json",
  "name": "<your-documentation-title>",
  "logo": {
    "dark": "<logo-for-dark-mode>",
    "light": "<logo-for-light-mode>"
  },
  "favicon": "<link-to-a-favicon>",
  "colors": {
    "primary": "#0D9373",
    "light": "#07C983",
    "dark": "#0D9373",
    "anchors": {
      "from": "#0D9373",
      "to": "#07C983"
    }
  },

3. Tabs and anchors:
Tabs and anchors can be used to set up horizontal and vertical sections respectively in your documentation. Below are examples of tabs:

Below is an example of an anchor:

The settings for these components are handled by the tabs and anchors keys.

4. Navigation settings:
This section helps you to group the pages in your documentation. It is an array consisting of a group key, and a pages array where the pages for the group are added sequentially. Below is an example of how it is added:

git clone https://github.com/<your github username>/docs 

The settings above will translate to the image below:

The pages(introduction, etc.) are .mdx files in your project’s docs folder.

5. Nested navigation:
Nested navigation is commonly used to create subsections within a documentation. Below is an example of a nested navigation:

Below is a sample code to set up a nested navigation on Mintlify:

npm i -g mintlify

The code above nests a section/group within another section. The icon key beautifies the section title with an icon when rendered on a web page.

6. Footer settings:
The footerSocials key is used to add social media accounts related to the documentation. Below is an example:

How to add content

The Mintlify documentation guides you on how to add content to your documentation. I recommend you check out the documentation to learn how to add different content to your documentation.

Check out this sample documentation for inspiration on how to structure your own documentation.

Documentation writing tips

Below are few tips to help you write clear and user-friendly documentation:

1. Be as direct as possible: Avoid extraneous information that adds no value. Your documentation is for developers who want to use your package or tool in their next project so only show them what they need to achieve this.

2. Add a description or overview of your tool:
Before going into details on how to use your tool, briefly describe what your tool is and the problem it solves. This should be on the first page.

3. Add enough code samples:
This will help them understand how to use your tool without unnecessary errors. Code samples on installation, authentication, response samples, method arguments, etc are very important.

4. Errors and exceptions:
This will help users in debugging. Add a page to describe the kind of errors users may encounter when using your tool. Also show code samples for this.

Push the project to Github

Follow the steps below to push the project to Github:

1. Open a git bash terminal in your project and switch into the docs folder with the command below:

git clone https://github.com/<your github username>/docs 

2. Remove git from this folder with the command below:

npm i -g mintlify

This command removes .git from the docs folder to avoid issues when you want to push the entire project to Github.

3. Push the project to GitHub.

Deploy the documentation

Follow the steps below to deploy your documentation on Mintlify:
1. Login to your Mintlify dashboard
2. Click on the Settings tab

3. Change your Mintlify Github repo to your project’s repo

4. Activate the monorepo switch. This signifies that the docs folder exists within another project in a single repo.

5. Enter **docs as the path to the mint.json file in the new field that appears.**

6. Click the save button to save changes.

Your documentation can be accessed via the link displayed in the overview tab of your dashboard

Updating the Project

You’re most likely to make changes to your project and may need to redeploy it.

After making any updates in your project, ensure you push the changes to Github. Mintlify automatically picks up the new changes and updates your docs promptly.

Conclusion

In this tutorial, you learnt how to build documentation for a Python library using the docs-as-code approach.

Docs-as-code promotes collaboration and continuous integration on a project. When it comes to open source, docs-as-code allows people to collaborate seamlessly on a project while maintaining proper documentation that is up-to-date.

There are different REST APIs without SDKs or programming libraries. Select one that interests you and create something similar.

Keep building ?‍?!

FAQs

How can I test my documentation?

This feature is often used on large projects with multiple contributors. Documentation testing is run automatically when a pull request is made to the Project. If the test is successful, the changes are merged. Read this guide on how swimm offers automatic documentation testing to learn more.

Can I replicate this project in other programming languages?
Yes you can. Follow the procedures in this guide to get a similar result in your preferred language.

Are there other documentation sites except Mintlify?
Yes there are other documentation sites you can use. Some of them include: Gitbook, Readme, Docusaurus, etc.

The above is the detailed content of Docs-as-code in action: Documenting a Python library.. For more information, please follow other related articles on the PHP Chinese website!