Documenting with Sphinx tutorial: Part 4—Using git to push docs to GitHub

Part 4

In this final part of this tutorial, we’re going to get our documentation onto the ReadtheDocs platform. This involves two steps:

1. Pushing docs to a Github repository
2. Connecting the repository to a ReadtheDocs account

Watch the video or continue reading below:

Pushing docs to Github

In the command line, navigate to the repository folder and run
git status

This will show you the status of your files.

Git sees files in one of three ways:
1. Tracked: Files that have been previously staged1moved to a staging area where git is able to track changes to a file and committed.
2. Untracked: Files that have not been staged or committed.
3. Ignored: Files that you have explicitly told git to ignore

In our example, we’re going to ask git to ignore some files including .DS_Store2An empty file that insists on tagging along and the virtual environment folder (jublerenv).

Creating a gitignore file

1. In the command line, run touch .gitignore
2. Open the file with vim .gitignore
3. Press ‘i‘ to edit the file and then enter the files you want git to ignore. Enter / (slash) after the name if it’s a folder.
   In our example, we’re ignoring the .DS_Store file, the virtual environment, and the build and _templates folders (all the documentation is in the source folder so we can ignore build).
4. Press esc, :wq and press the Enter key to save and return back to the command line.

Git commands to push to Github

1. Run git status again to make sure it now has the gitignore file just created, and git is properly ignoring the files we asked it to.

Ok I got a bit forgetful here. In the image above, git tells us we’re on the master branch. You would create another branch at this point and do the steps below there. You never push anything straight to the master branch.
So to create a new branch run git checkout -b branchname Now git status should tell you you’re on your new branch and you can proceed with the add, commit and push steps below.

2. Add the files to the staging area: run git add .
This adds all untracked files to the staging area.

3. Commit the files: run git commit -m"enter message here"

4. Push the files to Github: run git push origin master. But because you created a branch, you would run git push origin branchname

5. Go to your Github account and refresh your repository page. You should now see the docs there!

Importing the repository on Read the Docs

1. Go to readthedocs.org and create a new account (or log in).
2. Click on Import a Project.

3. Click the button.

4. Type in your project name and repository URL which you can get by clicking the button on your Github page. Click Next when done.

5. Click on . RtD is now building your docs from your repository. This will take some time depending on the size of your repo. You will see a green message saying Build Completed when it’s done.

6. Click on . Your docs are now hosted on Read the Docs! Congratulations!