Publishing Your Own Data Science Book On The Web

Photo by Patrick Tomasso on Unsplash

Publishing your own Data Science documentation/book on the web

A guide on how to publish your own project documentation/book online using for free MkDocs and GitHub pages.

Introduction

Have you ever wondered how libraries commonly publish their documentation online? One of the most common ways to publish project documentation online is to use MkDocs .

MkDocs is a static site generator which uses just a list of Markdown files and a YAML configuration file in order to immediately generate your own website, which can then be deployed using GitHub pages for free in one line of code.

If you are looking for an example of a website generated using MkDocs, you can findhere the book I wrote about my research project “Alleviate Children’s Health Issues through Games and Machine Learning” of which I talked about in my previous article (Figure 1).

Figure 1: Example documentation project created using Mkdocs.

In this article, I am going to quickly walk you through how to generate your own online project documentation.

Creating a project

First of all, we need to install the MkDocs Python library.

pip install mkdocs

Once installed the library, we can then create a folder for our project and open a command prompt from that location. Running the following command, will then automatically create for us a Mkdocs project.

mkdocs new my-project-name

The project will then have a structure like the following:

-- my-project-name
  -- mkdocs.yml
  -- docs
     -- index.md

The mkdocs.yml file will be used in order to design the structure of our website, while all the Markdown files in the docs folder will be used to create the content of each of the different pages of the website. If you are not familiar with how to create text files using Markdown, you can find an introduction guide here.

A simple mkdocs.yml file automatically generated by creating a Mkdocs project will look something like this:

site_name: MkLorum 
nav:     
  - Home: index.md

We can then modify it to choose our desired website name (instead of MkLorum) and add multiple pages on the website navigation bar by simply adding new pages under the nav tag (specifying on the left the nav button name and on the right the file name in the docs folder). Finally, it is also possible to stylise our website either making use of a pre-installed theme (eg. readthedocs ) or choosing a theme from the ones available in the Mkdocs community .

An example, of a more personalised mkdocs.yml file, is available below.

site_name: my_website_name
nav:     
  - Home: index.md     
  - About: about.md
  - Contacts: contacts.md
theme: readthedocs

In the docs folder, we can instead find an automatically created index.md file, which we can then personalise for our own website. We can then add as many pages as we want to the website by simply adding new Markdown files in the docs folder and then reference them in the mkdocs.yml file.

At each point in the development stage, we can then always observe how our website looks like by running the following command in the command line from our project location:

mkdocs serve

This will activate a local server and we would then be able to see our website at this address: http://127.0.0.1:8000 . As soon as our local server is running, in case we modify any file (and save the changes), they will be automatically displayed on the website.

Once added all the content to the website and checked that it is displayed correctly, we can then build the HTML and CSS files by running the following command:

mkdocs build

At this point, we are now ready to initialise our project with a GitHub repository. After that, we can then just run from the command our last command and our project will be then deployed online:

mkdocs gh-deploy

On the command prompt, will then be displayed the link at which our website will then be live. Alternatively, we can find this same link by going to our repository settings and looking for the GitHub pages options (running the command shown above, will in fact automatically generate a new branch called gh-pages , which will then be used to by GitHub to host our documentation website).