GitHub, Pull Requests, and ReadTheDocs¶
This lesson will walk through the powerful combination of two Web sites – github.com for collaboratively editing documents, and readthedocs.org for hosting documentation and workshop Web sites. You’re probably all familiar with either GitHub or a similar code-hosting Web site, BitBucket; ReadTheDocs is what we use to host this site, and it’s based around the Sphinx documentation generator. Sphinx is used to build the Python documentation, among other things.
Alternatives: You could do very similar things with Markdown and github pages, or a variety of other systems. The overall workflow is largely the same, however!
Learning goals:
At the end of this lesson, students will understand:
- forking, online editing, and pull requests on github;
At the end of this lesson, students will be able to:
- connect a sphinx site to readthedocs;
- collaboratively update sphinx sites through pull requests;
The lesson¶
author: | Titus Brown |
---|---|
date: | Aug 28, 2015 |
Go to http://github.com/ngs-docs/angus/ and click “Fork” in the upper right.
Save this URL - this is YOUR ANGUS REPOSITORY.
Go to http://www.readthedocs.org/ and set up a ReadTheDocs site for YOUR ANGUS REPOSITORY.
- Log in
- Select “import a project”;
- Click “connect to github”;
- Authorize the application;
- Click “Import a github repository”;
- Click “Sync projects;”
- Find YOUR ANGUS REPOSITORY;
- Click “create”;
- Change the name to ‘angus-USERNAME’;
- click “next”;
Now, view the docs (upper right) and change the URL from ‘latest’ to ‘stable’. This is YOUR ANGUS READTHEDOCS site.
(Everybody wait while Titus adds something to ngs-docs/angus/.)
Merge in Titus’s update into their own repository.
- Go to YOUR ANGUS REPOSITORY.
- Click “Compare” (above file listing, to the right); You should see “nothing to compare”.
- Click on “switching the base”;
- Click “Create pull request”;
- Click “Create pull request” again;
- Click “Merge pull request”;
- Click “Confirm merge”
Everyone should now be able to see MY change at YOUR ANGUS REPOSITORY, and, after a few minutes, at YOUR ANGUS READTHEDOCS SITE.
Now, everybody fix something in YOUR ANGUS REPOSITORY.
- Go find a file you want to edit (suggest
week3.rst
, add affiliation); - Edit, commit.
- Wait for YOUR ANGUS READTHEDOCS SITE to update.
- Go find a file you want to edit (suggest
Submit a pull request.
- Go to a directory view in YOUR ANGUS REPOSITORY.
- Click “compare”;
- Click “Create pull request”;
- Click “Create pull request” again;
(Wait for Titus to merge in your pull request.)
Changes will now appear on the main angus RTD site
WINNAGE.
A short guide to creating your own Sphinx repository¶
Create a virtualenv:
python -m virtualenv env
. env/bin/activate
Install sphinx:
pip install sphinx
Create a new directory for your docs:
mkdir my-project
cd my-project
Run sphinx-quickstart:
sphinx-quickstart
(accept default for most questions; answer those you can’t.)
Build:
make html
Marvel at the contents of _build/html/index.html
.
Now, put into git:
git init
git add Makefile index.rst conf.py
git commit -am "initial commit"
Go to github, create a new github repo, and follow the instructions to “push an existing repository from the command line”.
Then connect that repository to ReadTheDocs as above.
LICENSE: This documentation and all textual/graphic site content is licensed under the Creative Commons - 0 License (CC0) -- fork @ github. Presentations (PPT/PDF) and PDFs are the property of their respective owners and are under the terms indicated within the presentation.
comments powered by Disqus