Contributing¶
This is a sphinx project, which generates documentation for Carleton College BIOL.338 Genomics & Bioinformatics.
To contribute, you must:
- Be able to edit markdown (easy!)
- Be able to run sphinx, to generate webpages from markdown (easy!)
- Be able to use git to upload file changes to github (also easy!)
How do these tools fit together?
- We write the docs in markdown, then use sphinx to render beatutiful webpages from them.
- We use Git/Github to store the current version of the project online.
- We can also use ReadTheDocs to automatically build/serve our website, based on the current files stored on Github!
Step 1: Markdown¶
Markdown is a fairly simple specification for formatting text.
Markdown lets you indicate that things should be bolded or italicized or seen as headers or links in “plain-text” (ie, by typing certain characters rather than pushing application-specific buttons).
You can even write $\LaTeX$ in Markdown, by enclosing your Latex stuff in $
.
For syntax reference: see commonmark.org/help. (Though keep in mind some Markdown rendering “engines”, like the one on GitHub, support slightly different syntax, beyond and even different than the syntax specified by CommonMark.)
Using Markdown¶
A nice way to write Markdown and see it rendered into a formatted documnt is to use the Atom text editor, with the fantastic extension Markdown Preview Enhanced.
Step 2: Sphinx¶
Installing Sphinx¶
- Install sphinx:
pip install sphinx
- Install the markdown extension:
pip install recommonmark
- Install the ReadTheDocs Sphinx theme:
pip install sphinx_rtd_theme
Note:pip
commands are run at the command line / in Terminal.
Using Sphinx¶
Prepare materials:
- Write your markdown documents and put them somewhere, like the
pages/
folder. - To control which files are included: edit the file
index.rst
- To alter other settings: edit the file
conf.py
Build the website:
- Run
make clean
in terminal to empty out the_build/
directory - Run
make html
in terminal to generate html from the markdown files. - Type
open _build/html/index.html
in terminal to view your website with your browser (or open that file using Finder.)
Note: A good example project, for inspiration on using sphinx/markdown is the Requests package, which is on Github. Look in theirdocs/
directory, find files likeindex.rst
and press theraw
button.
Step 3: Github¶
When you’re ready to push your changes to github.
With Permissions¶
If you have permissions to push to the Github repository, commiting and pushing your changes just requires a few lines:
# see what has changed
git status
# stage modified files
git add -u
# add any new files
git add <filename> <filename>
# commit changes
git commit -m "< write a msg like 'modify protocol 5'>"
# push changes to remote server (github)
git push
Without Permissions¶
If you don’t have Github pushing permission for this project, you should fork the project, commit your changes, then open a pull request. This is the way open source software gets built. Hooray for open source!!!
Here’s a good resource on this workflow: https://gist.github.com/Chaser324/ce0505fbed06b947d962