Creating Software Documentation in under 10 minutes with mkDocs | by Shreya Chaudhary | Towards Data Science

As you work on any project, documentation is extremely helpful, almost critical. Luckily, mkDocs created a nice, efficient method of creating documentation that looks both professional and is easy-to-use.
Software documentation is writing about your code and your project, explaining what it is about and how it works. This is important for open-source projects, team projects, and even personal projects.
By documenting your code you:
Make your code explainable for others you’re collaborating with (and for yourself when you later look back at your code).Keep track of all aspects of your software.Make debugging easier later on.Can have a universal space to keep your files.
Make your code explainable for others you’re collaborating with (and for yourself when you later look back at your code).
Keep track of all aspects of your software.
Make debugging easier later on.
Can have a universal space to keep your files.
It should only take at most 10 minutes to create the skeleton of your documentation with mkDocs. Spending 10 minutes to document now is worth having to spend countless minutes struggling to debug your code and explain your code to your coworkers and yourself later.
To use mkDocs, you’ll need pip. You can find instructions on how to install pip here. If you have pip, make sure to update it, then install mkDocs. While you install mkDocs, you should also pick a theme (check out the options here). In the example, we picked the material theme.
pip install --upgrade pippip install mkdocspip install mkdocs-material
Now you’re ready to create your documentation. Run the below command, but replace PROJECT_NAME with whatever your project name is.
mkdocs new PROJECT_NAMEcd PROJECT_NAME
You should see a file called mkdocs.yaml and a folder called docs. The folder will have a single markdown file, index.md.
To run the documentation, use mkdocs serve and then go to http://127.0.0.1:8000/ in your browser.
Open mkdocs.yaml and you should see the following:
site_name: My Docs
We’re going to edit this document. First, we’ll create a generic outline; feel free to fill in the placeholder variables. The theme is what we pip installed in the past.
site_name: NAMEnav:  - Home: index.md  - Page2: page2.md  - Section1:    - Subpage1: subpage1.md    - Subpage2: subpage2.mdtheme:  name: THEME_DOWNLOADED
For example, imagine that I wanted to create documentation for an amusement park simulation. This is what I would write in mkdocs.yaml:
site_name: Amusement Park Simulationnav:  - Home: index.md  - About: about.md  - Games:    - "Ping Pong": games/ping.md    - Balloon: games/balloon.md  - Rides:    - "Scary Coaster": rides/scary.md    - "Drop of Doom": rides/drop.mdtheme:  name: material
Note that all the folders and directories mentioned in mkdocs.yaml will be in the docs directory. This is how my structure would look:
PROJECT_NAME/    docs/        index.md        about.md        games/             ping.md             balloon.md        rides/             scary.md             drop.md    mkdocs.yaml    Add the rest of your code here
If you don’t want several documents, categories can also be created with markdown header syntax. If you’re unfamiliar with .md files, you can learn more about the syntax here.
To end, we’ll host our documentation on GitHub Pages. Simply run mkdocs gh-deploy. It should create a new branch in your repository that will host your site at USERNAME.github.io/REPOSITORY_NAME.
And that’s it! You’ve successfully created documentation for your project. If you want to learn how to further customise your documentation or other mkDocs options, visit their website here. Check out my GitHub repository for this tutorial here and the deployed website here.
Make sure that you choose to use either tabs or spaces. mkDocs doesn’t allow a combination of both.
If there are spaces in the name, add quotation marks.
If you’re getting a 404 error, that means that you’re probably missing a file. Check docs to make sure your file exists there.
Note that organisations do not support GitHub pages.