Mitya's Self-Explanatory

Creating documentation for my project with AI in one hour

I have a Python library called tinybear that contains all simple tools I have used to work with files in different formats. It is published on pypi.

I was too lazy to write a blog post about publishing my project, but, in a nutshell, poetry makes these things rather easy.

Now, while moving in a direction of project management in IT, and having recently got a referral for a technical writer role, I decided, it was time to create at least some simple documentation for tinybear.

Today it took me about an hour to get this done using Perplexity and Qodo (this is not an advert). I used Perplexity to research options for creating documentation and then Qodo in my IDE to suggest additions/changes to project files.

Choose an approach

I chose the approach that is considered the simplest one: MkDocs + GitHub Pages. Sphinx is not needed for simple projects.

I already have GitHub Pages (you know that since you're here), so tinybear documentation cannot just be at https://lemontree210.github.io. I thought it would be a problem, but turns out I can easily deploy my docs to a "subdirectory" (in my case, https://lemontree210.github.io/tinybear/).

Change settings of the repo

The GitHub Action we're going to set up will need to create and write to a separate branch, which is common practice for hosting docs on GitHub Pages.

The action will fail if repo workflow permissions are set to read only.

So at https://github.com/[user]/[repo]/settings/actions you need to scroll down to "Workflow permissions" and choose "Read and write permissions".

Set up mkdocs

If you use poetry:

poetry add mkdocs mkdocs-material

Or with pip:

pip install mkdocs mkdocs-material

Create initial files by running from within the project directory:

mkdocs new .

This will create mkdocs.yml (configuration file) and docs/index.md (documentation homepage).

My configuration file looks as follows (adapted from this tutorial):

site_name: TinyBear Documentation
site_url: https://lemontree210.github.io/tinybear/
extra:
  base_url: /tinybear/
nav:
  - Home: index.md
  - Getting Started: getting_started.md
  - Usage: usage.md
  - API Reference: api.md
docs_dir: docs
site_dir: site
theme:
  name: material
  features:
    - navigation.instant  # ⚡ Instant loading
    - navigation.tracking  # 📊 Track scroll position
    - navigation.tabs.sticky  # 📌 Sticky navigation
    - navigation.top  # ⬆️ Back to top button
    - search.suggest  # 🔍 Search suggestions
    - search.share  # 🔗 Share search
    - header.autohide  # 🎩 Auto-hide header
    - content.code.annotate  # 💡 Code annotations

Create actual documentation

I used Qodo to amend index.md and create MarkDown files for "Getting Started", "Usage" and "API Reference", which are standard sections of any documentation.

Check locally

mkdocs serve

Starts a local server so you can look at the docs before pushing to the remote repo.

Set up GitHub Action

I created deploy.yml in .github/workflows directory:

name: Deploy MkDocs to GitHub Pages (gh-pages branch)

on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: 3.x
      - name: Install dependencies
        run: |
          pip install mkdocs mkdocs-material
      - name: Build docs
        run: |
          mkdocs build --site-dir site
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_branch: gh-pages
          publish_dir: ./site

Set up Pages for the repo

In Settings -> Pages (https://github.com/[user]/[repo]/settings/pages) you need to set up deployment with "Source" set to "Deploy from a branch" and "Branch" set to gh-pages and directory within this branch set to /root. As you can see in YAML configuration above, the gh-pages branch will be used as source for GitHub Pages. So, the Action takes what's on master now, puts it into gh-pages and GitHub Pages take content from there.

Test online

Since I don't push directly to master, I had a separate branch for introducing this new feature. Obviously, I want to see whether GitHub Pages render the docs fine before. So I temporarily amend the deploy.yml, replacing the first line as follows:

on:
  push:
    branches:
      - feat/add-mkdocs  # this is the branch from which I created a PR to merge the branch into master

Then, after pushing to this branch, you can check status of your actions in "Actions" section at https://github.com/[user]/[repo]/actions.

If actions run fine and you see that GitHub Pages renders the docs (in my case at https://lemontree210.github.io/tinybear/), remember to revert the change in branch name back to master (or main if your repo has main as main branch).

Merge your PR

And check Actions to make sure they ran, then refresh docs page to make sure the documentation is shown.

Publish on PyPi

With poetry, I first updated pyproject.toml to include links to docs:

[tool.poetry]
name = "tinybear"
version = "0.0.1"
description = "Where you don't need pandas yet. Tools to work with TXT, CSV, HTML, XLSX etc."
documentation = "https://lemontree210.github.io/tinybear/"
# ...

[tool.poetry.urls]
Homepage = "https://github.com/lemontree210/tinybear"
Documentation = "https://lemontree210.github.io/tinybear/"

and then ran:

poetry build
poetry publish

Now on PyPi I can see a link to my documentation in a sidebar.

P.S. It took me one hour to do all of this and then two hours to describe it in a blog post :)