New GitHub Project¶
Create a GitHub Account¶
Before you can start a project on GitHub, you will need to Get Set Up with GitHub by creating an account.
Go to https://help.github.com/articles/set-up-git/ and follow the directions to create your account.
Set Up Git¶
If git is not already on your system, go to http://git-scm.com/downloads and download it.
It is easiest to install Git on Linux using the preferred package manager of your Linux distribution, for example on Debian/Ubuntu:
apt-get install git
OR
sudo apt-get install git
GitHub for Windows or GitHub Desktop is very convenient for Windows users.
For all operating systems it’s a good idea to set your credentials via:
git config --global user.name "YOUR NAME"
git config --global user.email "YOUR EMAIL ADDRESS"
For privacy concerns, consider using an email address of: <username>@users.noreply.github.com See: Keeping your email address private
These housekeeping tasks are covered at https://help.github.com/articles/set-up-git/.
Create New Repository¶
The instructions to create a new repository are at https://help.github.com/articles/create-a-repo/.
It is six simple steps to create the new repo.
- click “New repository” (+ sign at upper right of https://github.com/)
- create a short, memorable name
- add a description
- choose between public or private (public is simpler)
- Select
Initialize this repository with a README(allows immediate cloning) - Use the option to create a .gitignore file, select Python
- This will ignore things python creates that just get in the way; things like __pycache__ and .tox subdirectories, *.pyc and *.pyo files, .coverage files and much more.
- You can also select a license
- Select
- Click Create repository
Clone Your New Repository¶
Suppose that your GitHub username is “MrEd” and your project name is “ApplePy”, then at the GitHub website of your new repository:
for example... https://github.com/MrEd/ApplePy
If your browser supports it, click the Clone in Desktop button to create a local clone. Start adding and editing files in the local repository and committing them whenever you like.
Note
When you Clone in Desktop, a new subdirectory will be created below whatever directory location you select. That new subdirectory will have your projects name. You do NOT need to first create a subdirectory with your projects name.
Note
You may want to delete README.md and replace it with README.rst (Replace Markdown with ReStructuredText since sphinx uses *.rst files.)
If you use git from the command line, you should navigate to the location where you want the cloned project to be stored. Look for an entry box on the project’s GitHub web page just above Download ZIP called HTTPS clone URL. Copy and paste that URL into the command:
git clone <pasted url>
FOR EXAMPLE
git clone https://github.com/mred/applepy.git
You will now have a cloned project.
If you have been doing some development already, simply paste your existing files into the new repository and commit them.
Set up ReadTheDocs¶
You’ll want your documentation to automatically update to your ReadTheDocs page, whenever you commit changes to GitHub.
Go to https://readthedocs.org/ and Log In. (If you do not yet have an account on ReadTheDocs, look at Read the Docs.
Logging in to ReadTheDocs, takes you to the ReadTheDocs dashboard. Select Import a Project followed by Import from GitHub.
You may have to select Sync Your GitHub Projects to see the new project.
Select the Create button for the new project.
If you select “Edit advanced project options” and hit the Next button, You can select Python as the Programming Language and paste the GitHub url for your project as the Project homepage:. (“https://github.com/MrEd/ApplePy” in the previous example)
Finally select the Build button.
Given a little time, the View Docs button will jump to your documentation. (http://applepy.readthedocs.org/en/latest/ in the previous example)
Automatically Update ReadTheDocs¶
Your docs on ReadTheDocs should update whenever you push updates to GitHub. To verify this, go to your new repository:
for example... https://github.com/MrEd/ApplePy
and click the Settings button.
Click Webhooks & Services at the upper left. You should see a ReadTheDocs link in the Services section.
Click ReadTheDocs and verify that it is set to Active. If it’s active, your good.
Turn on Travis CI¶
While in the Webhooks & Services option from the above ReadTheDocs section, select the drop-down menu for Add service and select Travis CI. After activating, you can push the Test service button to run Travis CI immediately.
You may have to go to your Travis CI profile page, Sync your repositories and activate the service. (for example, https://travis-ci.org/profile/<your account name> )
Now, whenever you push new code to GitHub, Travis CI will run.
Also make sure the link in your README.rst file to the Travis CI build status is correct. It should look something like:
.. image:: https://travis-ci.org/<MyGitHubName>/<MyProjectName>.svg?branch=master
:target: https://travis-ci.org/<MyGitHubName>/<MyProjectName>