How to build a documentation website for your project
Today I want to tell you how to build and deploy a documentation website for your project. I'll use mkdocs for a website, Dokka for API documentation, and GitHub Actions as a CI to put everything together and deploy.
Let's start with creating a sample project that we will use as a source for our future documentation. I call it Moove it's a multi-module project. It contains core, shared, design-system, tickets and app modules. It's a simple app with few screens and layered architecture.
The final documentation will contain two parts: API docs aka Javadoc and tutorial pages. Let's start by creating the folder android-docs in the project's root directory.
The API Documentation
To build API documentation, we are going to use Kotlin Dokka. I'm not going deep into the full API Dokka provides, but use only a basic setup. Apply this in the root build script of your project.
Because we have a multi-module project we need to dokkaHtmlMultiModule task. To build the API Javadoc we need to run the ./dradlew dokkaHtmlMultiModule task. By default, the output directory is set to /build/dokka/html and /build/dokka/htmlMultiModule but we want to put results into android-docs/docs/api. That's why we put this outputDirectory.set(file("android-docs/docs/api"))line into the script above. You can run tasks and check generated documentation. You'll find many files and folders but we particularly interested in index.html , open it with the browser and check if everything is as you expected, if not you can do customization. Now we can move to the next step and build our website.
The Documentation Website
For the website, we will use mkdocs. It's quite a popular and highly customized tool for that. I'm not going to dive deep into every aspect of it, for that better to check official documentation.
To do setup mkdocs we need to use Python. So if you don't have it on your system, do it before the next steps.
We go to the android-docs directory and only after that do the setup of the Phyton environment. Then install mkdocs with Phyton and finally run mkdocs new . it will create the initial website. After that, you'll see the next files.
Now we can use mkdocs.yml file to do customization we want: light/dark theme, color scheme, copyright, and many other stuff. You can see the example in the project. Also, you can see index.md it's a starting page that you can modify with content using Markdown. As an example, I put information about project architecture. You can create Markdown files as many as you want and put them in docs folder but we must keep index.md as an entry point. Now let's test how our website looks by running the next command.
As a result, you'll see in the terminal the local address of the website such as Serving on http://127.0.0.1:8000/. Click it and a web browser will open the website. Keep the terminal open and try to change the source code of your website and mkdocs rebuild the site instantly, a nice feature for developing and testing. Our next step is to set up pages of our site and use the API Javadoc we generated as a source for one of the pages. Open mkdocs.yml and add the next lines.
For Getting Started use index.md as a source. For the API page, we need to use index.html we generated with Dokka previously.
Probably noticed the next line site_dir: html we need to set the name of the folder where we put the generated website. I'll back to it a bit later and you'll see why the name should be html.
Let's move forward to build the website and store it in android-docs/html for that, we need to run the next command.
As a result, mkdocs creates the html folder with all sources. in it, you can find index.html it's the entry point to your website.
Congratulations, we made it!
Now you probably thinking about how to deploy this website and make it available to everyone.
I will offer you two solutions how to do that:
- GitHub Pages
- Build a Docker image, use nginx as a web server for our static site, and then you can use the image to deploy your site using DigitalOcean or other clouds
The GitHub Pages
I will use GitHub Actions as a CI to build and deploy documentation. Let's write a small bash script, we are going to need it for CI. We put their commands described above.
Now we are ready to write workflow for GitHub Action. Before we go forward if you are not familiar with GitHub Pages then read how to set up deployment to the GitHub Pages through GitHub Action.
I want to pay attention to the next steps:
- Generate Docs — where we used the bash script we had written.
- Upload documentation zip archive — it's an example of how to get a zip archive if you need
- Setup Pages, Upload artifact, Deploy to GitHub Pages — steps we need for GitHub Pages deployment
As a result of this workflow, we have a URL to our website.
Docker image
If you want to make your documentation with private access, shield by authorization, and manage access for that you probably need to set up your server. For that, you can build a Docker image. Create a Dockerfile in you android-docs .
The first line uses Nginx as a server for static websites. Second line we need to copy the site we built before into the nginx htmldirectory. This directory should have index.html an entry point. That's why we named our site dir as html , to make this step simpler.
Let's add steps to the workflow required to build a Docker image and upload it to the GitHub Packages.
You can set the name of the image. After the successful run, you will find your Docker image in the packages where you can pull the image
Then you can use the image to deploy your site with DigitalOcean or other clouds.
Congratulations! We're done. No rocket science and I like it.
Thank you for reading!
