Rapid Way to Publish Python Docs With Free Hosting and Domain

If you are interested in publishing wikis, tutorials, or documentation of your project online, either you are confronted with installing and setting up a full-featured CMS like WordPress or learning HTML, JavaScript, and additionally a web framework.

I would like to show you another option, where you can simply create a website based on markdowns and publish it on free web hosting. And as a bonus, I will show you how to claim a free domain like my-project.py.wiki.

Turning markdowns into a website

First, we need software that is able to turn markdowns into static web content. This software is called static site generators. In my personal experience, MkDocs is the most straightforward choice for python users. However, there are other noteworthy options like Sphinx or Pelican.

Let's begin:

pip install mkdocs
mkdocs new my-great-project
cd my-great-project
ls -R

The folder should look as follows:

mkdocs.yml    # The configuration file.
docs/         # contains all the markdowns
    index.md

Now you can move all markdowns to the folder docs. In fact, the dev-server supports auto-reloading, which means it detects the markdown changes and refreshes the page automatically. Let's start dev-server with mkdocs serve. Make some changes to index.md and save it.

The configuration file has only two required fields site_name and site_url. By adding the nav field, you can specify the order and name of the navigation items. Even hierarchical navigation is supported out of the box. The last field site_dir defines where the website will be generated. It will be useful later on.

site_name: Foo Docs
site_url: https://foo.py.wiki/
nav:
  - Home: index.md
  - Dev Guide:
      - Setup: setup.md
      - Bug Report: bug_report.md
site_dir: public/

Let's generate it and the folder public should now contain some static files.

mkdocs build
ls public/

In case you are wondering which theme py.wiki is using, it is mkdocs-material. More custom themes can be found here MkDocs Wiki: Themes.

Hosting your docs on GitLab

GitLab provides a service called GitLab Pages which enables to publish static websites directly from a GitLab repository. As an alternative, you could also use Github Pages or Cloudflare Pages.

Before initializing a git repository, please add the following lines to .gitignore so that the build files will not be tracked.

site/
public/

We need the file requirements.txt for the CI/CD environment.

echo 'mkdocs==1.3.0' > requirements.txt

GitLab has a built-in CI/CD service. We now have to configure this service so that MkDocs generates the website in the folder public at the stage deploy.

Let's create a file .gitlab-ci.yml in the root folder as follows:

image: python:3.10-bullseye

stages:
  - deploy

before_script:
  - pip install -r requirements.txt

pages:
  stage: deploy
  script:
    - mkdocs build --verbose
  artifacts:
    paths:
      - public

Now with each push on the remote branch, our documentation is built and published. After the first build, your website should be visible at https://{username}.gitlab.io/{project-name}.

In case you prefer to trigger the build process manually, you can add the following line:

  ...
  artifacts:
    paths:
      - public
  when: manual # <---- add this line

Go to Pipelines from the CI/CD menu, you will see that this pipeline was skipped. If you click on the stage, you have the possibility to start this stage.

Claiming a stylish domain

When I came across JavaScript libraries with the domains *.js.org, I noticed how easy the domains are to remember. Personally, I found that js.org provides a great service for the JavaScript community, so I wanted to do something similar for the Python community.

That is way I created the service py.wiki, where people can register domains *.py.wiki for Python-related projects.

Think of a suitable domain. Below are some ideas on how to determine the appropriate domain name:

• if library "foo-bar" => foo-bar.py.wiki
• if library "foopy" => foo.py.wiki
• if gitlab page "foo.github.io/bar" => foo.py.wiki
• if gitlab page "foo.github.io/bar" => bar.py.wiki

Go to Pages in the Settings menu and click on New Domain. Enter your desired domain name. After clicking on Create New Domain, the DNS and Verification status fields are displayed. Remember this information.

Let's fork the repository py.wiki. We have to extend the file dns_config.yml. There 2 ways to add our domain under CNAME. With the first approach, the Cloudflare proxy is automatically enabled, which means Cloudflare will cache the content of your website.

CNAME:
  py.wiki: bigaru.gitlab.io

In case you do not want that your content is cached, you can disable the Cloudflare proxy as follows:

CNAME:
  py.wiki:
    name: bigaru.gitlab.io
    proxied: false

Insert your domain in alphabetical order:

CNAME:
  foo.py.wiki: foo.gitlab.io
  py.wiki: bigaru.gitlab.io
  www.py.wiki:
    name: bigaru.gitlab.io
    proxied: true

In the case of GitLab Pages, we additionally need to add a TXT record to verify the ownership. Therefore, simply append with your entry to TXT:

TXT:
  _gitlab-pages-verification-code.py.wiki: gitlab-pages-verification-code=0000
  _gitlab-pages-verification-code.www.py.wiki: gitlab-pages-verification-code=0000
  _gitlab-pages-verification-code.foo.py.wiki: gitlab-pages-verification-code=0000

After saving and pushing to the remote branch, let's open a new merge request. Choose the template 'new-domain'. Afterward, fill out the form and create the merge request.

Once your merge request is accepted and merged, the CI server will automatically update the DNS records on Cloudflare. The DNS probation may take some time. Thereafter, your page will be accessible under a fancy domain.