Publishing Your Own Data Science Book On The Web

栏目: IT技术 · 发布时间: 5年前

内容简介:A guide on how to publish your own project documentation/book online using for free MkDocs and GitHub pages.Have you ever wondered how libraries commonly publish their documentation online? One of the most common ways to publish project documentation onlin

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).

Publishing Your Own Data Science Book On The Web 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).


以上就是本文的全部内容,希望对大家的学习有所帮助,也希望大家多多支持 码农网

查看所有标签

猜你喜欢:

本站部分资源来源于网络,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有,如转载稿涉及版权问题,请联系我们

人类思维如何与互联网共同进化

人类思维如何与互联网共同进化

[美] 约翰·布罗克曼 / 付晓光 / 浙江人民出版社 / 2017-3 / 79.90元

➢人类是否因互联网的诞生进入了公平竞争的场域? “黑天鹅事件”频频发生,我们的预测能力是否正在退化? 智人的第四阶段有哪些特征? 全球脑会使人类成为“超级英雄”吗? 虚拟现实技术会不会灭绝人类的真实体验? 还有更多不可预知答案的问题,你将在本书中找到属于自己的答案! ➢ 我们的心智正和互联网发生着永无止境的共振,人类思维会因此产生怎样的进化效应?本书编者约翰•布......一起来看看 《人类思维如何与互联网共同进化》 这本书的介绍吧!

JSON 在线解析
JSON 在线解析

在线 JSON 格式化工具

随机密码生成器
随机密码生成器

多种字符组合密码

XML 在线格式化
XML 在线格式化

在线 XML 格式化压缩工具