Read the Docs Setup & Publish

Read the Docs

Read the Docs simplifies documentation by automating building, versioning, and hosting of your docs for you.

Getting started

Read the Docs requires a repository (a.k.a. repo) with a minimum of:

  • A specifically formatted mkdocs.yml YAML file
  • A docs/ folder containing an index.md file

A sample mkdocs.yml YAML file (YAML = YAML Ain't Markup Language)

site_name: My first readthedocs
theme: readthedocs
pages:
- Introduction: index.md
- Getting started: getting_started.md

Hands-on

GitHub Setup

  1. Sign into GitHub.
  2. Fork our sample repository, the button is in the top right corner of the repository.

Note (from the glossary): A fork is a Git concept of copying a repository from someone else's ownership to your ownership, all the while maintaining the history

Read the Docs Setup

  1. Log into readthdocs.org with your GitHub account.
  2. Click the Import a project button which will bring you to the Import a Repository menu.
  3. In the Import a repository menu select your forked repo with the + (plus) sign.
  4. Adjust the Name to something short and memorable for the documentation webpage name.
  5. Click Next on Project Details.
  6. Go to the Admin tab in the top right and then Advanced Settings on the left.
  7. Change Documentation type: to Mkdocs (Markdown).
  8. Click Save at the bottom.

Publish

  1. To see publishing progress go to the Build tab and find the latest build.
  2. When it says Build completed you can click the View Docs button to view those docs.

Discussion: Your new site

Take a look at the front page of your newly published readthedocs.org site. What advice might you suggest that you don't see there?