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!)
Step 1: Markdown¶
Learning:
- Markdown is a simple way to format text.
- You can indicate in plain-text (ie, by typing special symbols rather than pushing application-specific buttons) that things should be bolded or italicized or seen as headers or links.
- See commonmark.org/help for quick reference. (Though note some Markdown “engines” support other syntax, beyond and even different than the syntax specified by CommonMark.)
Using:
- A nice way to edit markdown and see it rendered into HTML is to use the Atom text editor, with the fantastic extension Markdown Preview Enhanced.
Step 2: Sphinx¶
Installing:
- Install sphinx:
pip install sphinx
- Install the markdown extension:
pip install recommonmark
- Install the ReadTheDocs Sphinx theme:
pip install sphinx_rtd_theme
Using:
- Edit the file
index.rst
to alter which files are included - Edit the file
conf.py
to alter settings - 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.
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:
# 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 "<msg like 'modify to protocol 5'>"
# push changes to remote server (github)
git push