Sphinx, Webhooks, and Bitbucket Documentation

Sphinx, Webhooks, and BitbucketDocumentation

Release 1.0

Adelaide Rhodes, Ph.D.

March 30, 2016

Contents

1 Introduction 1

2 Start of the Tutorial 32.1 Paragraph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.2 Inline markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42.3 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.4 Pre-formatted text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.5 Section Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3 Introduction - “Chapter I” 9

4 Start of the Tutorial - “Chapter II 114.1 Paragraph - Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.2 Inline markup - Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.3 Document titles and subtitles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.4 Copy and Paste your page into the following website to check your syntax: . . . . . . . . . . . . . . 124.5 Correct any errors that you can see. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124.6 Move on to Part II . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

5 Additional Readings 13

6 OPEN an EC-2 INSTANCE on Amazon 15

7 INSTALL DEPENDENCIES: 17

8 Running Sphinx the First Time 19

9 Open your HTML file 23

10 MAKING OUR DOCUMENTS LOOK NICE 25

11 Changing the Theme on the Local Computer or Remotely on the EC2 27

12 Webhooks and Automation 29

13 Create a Repository 3113.1 Bitbucket version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3213.2 Github version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

14 Readthedocs.org 33

i

15 Automating the Web Hook 39

16 Changing the style pages for Read the Docs 43

17 In Summary 4517.1 Set up Read the Docs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

18 Restructured Text for Building Webpages for Git Repositories 4918.1 Description: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4918.2 Learning Objective: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4918.3 Webtools to Sign up For Beforehand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

ii

CHAPTER 1

Introduction

reStructuredText is a simplified mark-up language. These simplified patterns are interpreted by a HTML converter toproduce “Very Structured Text” read by a web browser. I started using reStructuredText after forgetting one too many</p></a></strong> in my html files. I would get overwhelmed by the multiple lines of code and would give up infrustration after a few minutes of trying to keep my eyes uncrossed.

In reST, there are only a few rules to remember, and most of them hinge upon the special symbols that come beforeand after regular text. I usually start by writing a simple piece of text, then adding in the symbols from top to bottom.You may like to add the symbols as you go.

1

Sphinx, Webhooks, and Bitbucket Documentation, Release 1.0

2 Chapter 1. Introduction

CHAPTER 2

Start of the Tutorial

Before beginning, take a few minutes to download a good text editor for your computer if you do not already have one.

I recommend Notepad++ or Sublime3 for Windows. TextEdit is okay, in windows, but does not have the nice format-ting options of Notepad++. Sublime3 automatically recognizes and colorcodes several programming languages.

I recommend Atom or Text Wrangler for Mac. Atom has the added function of being able to preview certain typesof markdown (not reST) in an adjacent window and will allow direct edits to a github repository within the program.Text Wrangler allows files to be saved in Unix-code directly, and has a spellchecker built in.

The most important feature is to have a text editing tool that does not add back-end coding (e.g. Microsoft Word) andthat has line numbering along the side. This will be important later when Sphinx builds the Makefile.

If you do not have a text editing tool installed, please do so now. Fastest installs are Notepad++ for windows and TextWrangler for Mac.

Windows Text Editors:

• https://notepad-plus-plus.org/download

• https://github.com/atom/atom/releases/download/v1.5.3/atom-windows.zip

• https://www.sublimetext.com/3

Mac Text Editors:

• https://s3.amazonaws.com/BBSW-download/TextWrangler_5.0.2.dmg

• https://atom.io/


2.1 Paragraph

The basic building block of reST is the paragraph.

A paragraph is a set of text that is separated by blank lines, one line is enough.

A paragraph that is indented in reST will be indented on the web page.

Paragraphs that need to be aligned should start in the same location (in this case all the way to the left).

3

https://notepad-plus-plus.org/download

https://github.com/atom/atom/releases/download/v1.5.3/atom-windows.zip

https://www.sublimetext.com/3

https://s3.amazonaws.com/BBSW-download/TextWrangler_5.0.2.dmg

https://atom.io/



2.2 Inline markup

Symbols used in resStructeredText (reST) asterisk “*”,”backslash “”,grave accent “‘”

Simplest case: inline markup with *italics* and **bold**

Simplest case: inline markup with italics and bold

Yes, it is that simple.

If the “*” is inside a line, say an equation 6*30=180, reST will ignore it. If the * is all by itself, surrounded by spaces,reST will ignore it.

What if you have a line you want to start with “*”, but not be italicized?

2.2.1 First method:

Place a backslash in front of the symbol.

Now the html interpreter will see the \*word* and ignore the italics symbol.

Now the html interpreter will see the *word* and ignore the italics symbol.

This is similar to the “escape” function that is used for in regex, or when you are transferring a file with spaces in thename. ignores the “specialness” of the character.

2.2.2 Second method:

That is where use a new symbol:

“‘” = grave accent, sometimes referred to as “backtick” or “back quote” In Mac keyboards, this accent is foundunderneath the ~, to the left of number 1.

Here is a guide for finding the grave in your computer:

http://superuser.com/questions/254076/how-do-i-type-the-tick-and-backtick-characters-on-windows

What about if the word is not inline, but at the beginning of a paragraph?

To ignore the asterisk in the following condition - place the phrase within double grave accents.

``*word*`` becomes

*word*

instead of word

This method is called “inline literals”, and I prefer to use this method, because it is more symmetrical to me. However,if you are using a lot of regular expression in your work, backslash may be more familiar to your style.

Some issues:

reST may not be nested content may not start or end with whitespace:

* text* is wrong,A backslash escaped space to work around that: thisis\ *one*\ word.Backslash will not work at the beginning of a paragraph, list item or section in some html interpreters.

4 Chapter 2. Start of the Tutorial

http://superuser.com/questions/254076/how-do-i-type-the-tick-and-backtick-characters-on-windows


2.3 Lists

Three kinds:

1. enumerated,

* bulleted, anddefinitions

indented text to define a term

If the left-hand side of the paragraph or aligns, you can have as many sublists as you want.

Lists must always start a new paragraph – that is, they must appear after a blank line.

2.3.1 enumerated lists

How to do it: Start a line off with a number or letter followed by a period ”.”, right parenthesis ”)” or surrounded byparentheses “( )”

1. numbers

1. upper-case letters. Information can be continued over several lines, to create a new paragraph, make sure toleave a blank line.

This is my second paragraph.

1. lower-case letters

(a) here is a sub-list starting at a different number

(b) it is up to you to check the sequence

1. upper-case roman numerals

1. lower-case roman numerals

1. numbers in parentheses

1. numbers with one right parentheses

Known issue: the different enumerated list styles are not always supported by every web browser.

2.3.2 bulleted lists

How to do it: Just like enumerated lists, start the line off with a bullet point character “-”, “+” or “*” :

• bullet point using “*”

– sub-list using “-“

* another sub-list using “+”

– another item

• bullet point using “*”

– sub-list using “-“

* another sub-list using “+”

– another item

Note: nested lists require blank lines before the beginning of the sublist

2.3. Lists 5


2.3.3 definition lists

definition lists consist of a term, and the definition of that term. The format of a definition list is:

what Definition lists associate a term with a definition.

how The term is a one-line phrase. The definition is one or more paragraphs or body elements, indented relative tothe term. No blank lines between term and definition.

2.4 Pre-formatted text

If I have something written out in a text document and I want to have it look exactly that way in reST, I can indicatethat the text is “preformatted” by adding ”::” to the end of the prior paragraph.

This is called a “literal block”. It only works if an indentation is provided for the text following the ”::”. The blockwill appear as a slightly different color on the page, depending on which format you choose for Sphinx.

An example:

Whitespace, newlines, blank lines, and **markup**(like *this* or \this) is preserved by literal blocks.

Your mistakes are retained as well, (note poor alignment here)

no more example

To hide the :: from the html version, just add a whitespace before the ::

If you are putting the pre-formatted text at the beginning of a section and there is no paragraph beforehand, you canjust put ”::” at the beginning of a line. Make sure to skip a line between that :: and the start of your pre-formatted text.:

_,:'/ _..._

// ( `""-.._.'\| / 6\___| 6 4| /\_ .--'(_'---'`)/ `'---`()

,' |, .'` |)\ _.-' ;

/ | .'` _ //` / .' '. , |

/ / / \ ; | || \ | | .| | |\ `"| /.-' | | |'-..-\ _.;.._ | |.;-.

\ <`.._ )) | .;-. ))(__. ` ))-' \_ ))'

`'--"` Rambo `"""`

2.5 Section Headers

You might have noticed that I have been interlacing my sections with non-alpha-numeric characters as I write thisdocument.



• Sections can be indicated by the following: = - ‘ : ‘ ” ~ ^ _ * + # < >

• The underline symbol must extend as long as the text, and appear immediately underneath the name of thesection

• Follow the underline symbol with a blank line

• Sections with the same symbol will be considered to be the same level in the text, so it is important to rememberwhich symbols you used for each level.

So far, we have the following set of sections laid out.

****************************Introduction -

****************************

********************************************Start of the Tutorial -

********************************************

Paragraph - Section===============================

Inline markup - Section===================================

First method: - Subsection------------------------------------

Second method: - Subsection-------------------------------------

This layout provides header text that looks like this:

2.5. Section Headers 7

CHAPTER 3

Introduction - “Chapter I”

9


10 Chapter 3. Introduction - “Chapter I”

CHAPTER 4

Start of the Tutorial - “Chapter II

4.1 Paragraph - Section

4.2 Inline markup - Section

4.2.1 First method: - Subsection

4.2.2 Second method: - Subsection

So, there is some method to this madness......

Another cool feature of section headers is that you can refer back to the link. You may have noticed that I just changedthe names of my sections slightly, because each section has to have a unique name. This is generally not a problemwhen you are organizing a science paper or setting up a class website. Dates are a good way to avoid repeating headernames. Sequential numbering of sections is another.

To link to a section or chapter in your document is very simple:

+ I can return to the "Introduction_"+ Or, if there is a space in the name of the header, I can use the grave accent inside the quotes, for example "`Section Headers`"+ You might want to be sparing in the number of headers, because they end up in the table of contents. Too many headers can clutter up the space.

• I can return to the “Introduction“

• Or, if there is a space in the name of the header, I can use the grave accent inside the quotes, for example “SectionHeaders“

• You might want to be sparing in the number of headers, because they end up in the table of contents. Too manyheaders can clutter up the space.

4.3 Document titles and subtitles

You may have noticed that my section list did not included

###########################reStructuredText Tutorial###########################

That is because the overline/underline style indicates a document title. This is shown by the html interpreter as acentered heading on your page. It is important to know that in some html interpreters, the overline/underline is

11


interpreted as a document “title”, and would be centered in the page. We are using Sphinx, which has it’s owndefinition of headers/titles, so it is best to stick to the conventions laid out below to get your reST file converted neatlyinto html using Sphinx.

Again, you can create titles and subtitles using the same characters as headers use, the main difference is that titles willbe centered on the page and headers will be left-aligned [IN CERTAIN WEB BROWSERS — BUT NOT A SPHINXCREATED WEBPAGE WHICH WE ARE CONSTRUCTING AFTER THE BREAK].

Some web browsers will interpret headers in a certain priority, so if you want to stick to these conventions, you shouldbe pretty safe, especially because we are using Sphynx to reinterpret our reST into html in the next part:

# with overline, for parts

* with overline, for chapters=, for sections-, for subsections^, for subsubsections", for paragraphs

Normally, there are no heading levels assigned to certain characters as the structure is determined from the successionof headings, but sticking to this convention will ensure that the web interpreter constructs it correctly.

4.4 Copy and Paste your page into the following website to checkyour syntax:

http://rst.ninjs.org/

or, a cool tool that can be added to your python scripts is:

https://launchpad.net/restview

4.5 Correct any errors that you can see.

4.6 Move on to Part II

Please follow this link.

OPEN an EC-2 INSTANCE on Amazon

12 Chapter 4. Start of the Tutorial - “Chapter II

http://rst.ninjs.org/

https://launchpad.net/restview

CHAPTER 5

Additional Readings

• http://www.sphinx-doc.org/en/stable/rest.html

• http://docutils.sourceforge.net/docs/user/rst/quickstart.html

• http://www.florian-diesch.de/doc/sphinx/themes-and-pygments-styles/index.html

• http://www.adamhyde.net/whats-wrong-with-markdown/

• http://evolvingweb.ca/story/writing-documentation-restructured-text-and-sphinx

• https://github.com/brandon-rhodes/sphinx-tutorial

• http://tjelvarolsson.com/blog/how-to-generate-beautiful-technical-documentation/

• https://pythonhosted.org/an_example_pypi_project/sphinx.html?highlight=release%20variable

• https://github.com/spatialaudio/nbsphinx/tree/0.2.4

• http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#include-other-rst-files-with-the-toctree-directive

13

http://www.sphinx-doc.org/en/stable/rest.html

http://docutils.sourceforge.net/docs/user/rst/quickstart.html

http://www.florian-diesch.de/doc/sphinx/themes-and-pygments-styles/index.html

http://www.adamhyde.net/whats-wrong-with-markdown/

http://evolvingweb.ca/story/writing-documentation-restructured-text-and-sphinx

https://github.com/brandon-rhodes/sphinx-tutorial

http://tjelvarolsson.com/blog/how-to-generate-beautiful-technical-documentation/

https://pythonhosted.org/an_example_pypi_project/sphinx.html?highlight=release%20variable

https://github.com/spatialaudio/nbsphinx/tree/0.2.4

http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#include-other-rst-files-with-the-toctree-directive


14 Chapter 5. Additional Readings

CHAPTER 6

OPEN an EC-2 INSTANCE on Amazon

All the work we are doing can be done on a laptop. It just requires installation of the sphinx-doc program and docutilsto get started:

http://www.sphinx-doc.org/en/stable/install.html]

Since some students may not have the ability to load the latest versions of these programs, it is possible to do a cleaninstall using the EC2 instance at Amazon Web Services.

http://angus.readthedocs.org/en/2015/amazon/index.html

Open an instance that is Ubuntu, and pick the free machine option (we are not loading very large files for this tutorial).

Remember to terminate your instance at the end of the tutorial.

15

http://www.sphinx-doc.org/en/stable/install.html



16 Chapter 6. OPEN an EC-2 INSTANCE on Amazon

CHAPTER 7

INSTALL DEPENDENCIES:

sudo apt-get install ghc6 libghc6-xhtml-dev libghc6-mtl-dev libghc6-network-devsudo apt-get install makesudo apt-get install docutilssudo apt-get install python-sphinx

wget https://github.com/yihui/ubuntu-bin/releases/download/latest/texlive.tar.gztar -xvf texlive.tar.gz

Let’s make a directory for our project.

mkdir ~/Tutorial

[Sphinx is relatively easy to download and install on Mac and PC, here are the instructions:

http://www.sphinx-doc.org/en/stable/install.html]

For the purpose of today’s tutorial, we have already installed all the programs we need on our instance. The directionsfrom here forward are very similar, except the extra step of transferring your html to your desktop if you are using theinstance to build an html.

In order to convert our reStructred text document to html, we are going to transfer our files to the instance, or elseinstall all the required programs to the desktop. S

From a terminal not inside your EC2 instance, you can type this at the command line:

scp -i ~/Desktop/reST.pem ~/Desktop/Tutorial.rst [email protected]:~/Tutorial

Note: make sure to do this from a terminal that is not in the EC2 instance, it’s relative path is based on your laptop.

Change the .pem file to the name and location of your file. Change the instance address to the instance in your address.

This may not work if you are on a Windows machine, but you can use a file transfer program, as detailed here:

http://angus.readthedocs.org/en/2014/amazon/transfer-files-between-instance.html

The reverse can be accomplished if you need to transfer the files back to your desktop for the bitbucket/github dragand drop step of the tutorial. If scp did not work for your previously, please use the ftp feature.

scp -i ~/Desktop/reST.pem [email protected]:/Tutorial/* ~/Desktop/

17




18 Chapter 7. INSTALL DEPENDENCIES:

CHAPTER 8

Running Sphinx the First Time

Since this is our first time creating a document using sphinx, let’s use the simplest option possible.

cd Tutorial~sphinx-quickstart

This is what you will see printed on the screen. Answer the questions as below. Hit Control +C if you make a mistake.————————————————–:

Welcome to the Sphinx 1.3.1 quickstart utility.

Please enter values for the following settings (just press Enter toaccept a default value, if one is given in brackets).

Enter the root path for documentation.> Root path for the documentation [.]

Press Enter to stay in this directory - the easiest thing to do is create a separate directory for each html page, place the.rst file you wish to convert in that directory and then build from sphinx-quickstart inside that same directory. Onceyou get good at the process, you may want to designate a base directory for all of your html pages that contains all ofyour work

You have two options for placing the build directory for Sphinx output.Either, you use a directory "_build" within the root path, or you separate"source" and "build" directories within the root path.> Separate source and build directories (y/n) [n]: y

Answer y

Inside the root directory, two more directories will be created; "_templates"for custom HTML templates and "_static" for custom stylesheets and other staticfiles. You can enter another prefix (such as ".") to replace the underscore.> Name prefix for templates and static dir [_]:

We are not setting this feature yet, so hit enter.

The project name will occur in several places in the built documentation.> Project name: Sphinx and reST Tutorial> Author name(s): Adelaide Rhodes, Ph.D.

Replace the project name and author name with your preferences.

Sphinx has the notion of a "version" and a "release" for thesoftware. Each version can have multiple releases. For example, forPython the version is something like 2.5 or 3.0, while the release is

19


something like 2.5.1 or 3.0a1. If you don't need this dual structure,just set both to the same value.> Project version: 1.0> Project release [1.0]: 1.0

Since this is the first time setting up our project, it is good to stick with the naming convention of “1.0” for bothoptions.

If the documents are to be written in a language other than English,you can select a language here by its language code. Sphinx will thentranslate text that it generates into that language.

For a list of supported codes, seehttp://sphinx-doc.org/config.html#confval-language.> Project language [en]: en::

Default is English.

The file name suffix for source files. Commonly, this is either ".txt"or ".rst". Only files with this suffix are considered documents.> Source file suffix [.rst]: .rst

We are using .rst as the option. .rst = reStructured text format.

One document is special in that it is considered the top node of the"contents tree", that is, it is the root of the hierarchical structureof the documents. Normally, this is "index", but if your "index"document is a custom template, you can also set this to another filename.> Name of your master document (without suffix) [index]: Tutorial

You can pick a different name if you like. Don’t put .rst on the end, or it will make a file that looks like:

Tutorial.rst.rst

Sphinx can also add configuration for epub output:> Do you want to use the epub builder (y/n) [n]: y

The epub builder is useful when transferring to the readthedocs.org format.

Please indicate if you want to use one of the following Sphinx extensions:> autodoc: automatically insert docstrings from modules (y/n) [n]: y> doctest: automatically test code snippets in doctest blocks (y/n) [n]: y> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y> coverage: checks for documentation coverage (y/n) [n]: y> pngmath: include math, rendered as PNG images (y/n) [n]: y> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: yNote: pngmath and mathjax cannot be enabled at the same time.pngmath has been deselected.> ifconfig: conditional inclusion of content based on config values (y/n) [n]: y> viewcode: include links to the source code of documented Python objects (y/n) [n]: y

Please answer yes to all of the questions, except pick either pngmath or mathjax for your math rendering program.Both cannot be enabled at the same time.

A Makefile and a Windows command file can be generated for you so that youonly have to run e.g. `make html' instead of invoking sphinx-builddirectly.> Create Makefile? (y/n) [y]: y> Create Windows command file? (y/n) [y]: y

20 Chapter 8. Running Sphinx the First Time


Answer yes.

Creating file ./source/conf.py.Creating file ./source/Tutorial Master.rst.Creating file ./Makefile.Creating file ./make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file ./source/Tutorial Master.rst and create other documentation source files. Usethe Makefile to build the docs. More than one building option is available, we are only using the html version for thistutorial.

Once the initial set of files has been constructed, sphinx can be triggered to rebuild the html file by typing:

cd Tutorialmake html

This allows us to automate any changes we make in our .rst file.

Let’s investigate the build — it won’t have any content yet.

cd ~/Tutorial/buildls

This is where our html file is located.

cd ~/Tutorial/sourcels

This is where our reST file is located.

nano Tutorial.rst

Sphinx places default text into the top of the file. You would want to keep the following parts:

.. Intro documentation master file, created bysphinx-quickstart on Mon Feb 29 15:24:58 2016.You can adapt this file completely to your liking, but it should at leastcontain the root `toctree` directive.

.. toctree:::maxdepth: 2

* :ref:`search`

This will build a search object and an index object for your website. Two useful tools once the website is published.This will create a table of contents that descends the top two levels. maxdepth: 3 would also work in our case. *:ref: search makes a search box in the html. This is helpful for very long files.

To add content to the Tutorial.rst file, you have two options. The easiest way to add content is to add the toctree andrefsearch commands from above to the top of your existing file and save it in the source directory. Next time you runthe make file, it will see all the content you have added to the .rst file in the source directory and generate an htmlversion in the build/html/ directory.

Or, if you have not written your content yet, open the .rst file in the source directory and start adding content afterthe default advanced directives made by the initial build. Be aware that any text or directive you do not erase will bevisible in the html file.

Once you have added some content to the .rst file in the source directory, we are ready to rebuild.

21


cd ~/Tutorialmake html

NOTE: You may get errors, this why it is helpful to have a line counting text editor on your desktop.

In order to see the result of our project, let’s bring the files to our desktop and open them up in a web browser.

scp -i ~/Desktop/reST.pem [email protected]:~/Tutorial/build/html/Tutorial.html ~/Desktop/

Note: make sure to do this from a terminal that is not in the EC2 instance, it’s relative path is based on your laptop.

Change the .pem file to the name and location of your file. Change the instance address to the instance in your address.

This may not work if you are on a Windows machine, but you can use a file transfer program, as detailed here:


Two good file transfer programs are the WinSCP for Windows and Cyberduck for Mac.

22 Chapter 8. Running Sphinx the First Time


CHAPTER 9

Open your HTML file

It is not very exciting... yet. If you built on the Mac version of sphinx, it may have the alabaster theme included in theinitial build.

However, once you have successfully created a format that you like, you can add new pages to your project by simplyadding them to the source directory where your first .rst file was located. It is a good idea to have an index.rst file atsome point, that will be useful for creating automated webpages using the readthedocs.org tool later on. Another goodfile to create is a simple README.rst file that describes the project and will serve as your frontpage on github.

The next phase is to spruce it up with style sheets, etc.

MAKING OUR DOCUMENTS LOOK NICE

23


24 Chapter 9. Open your HTML file

CHAPTER 10

MAKING OUR DOCUMENTS LOOK NICE

Right now, our style is a little bland.

Sphinx on the Mac will add a default style called “alabaster”.

Sphinx on our ubuntu install left it as basic.

This is easy to fix by providing a few more style sheets and changing our config file.

Working from the EC2 instance, the following files are required:

sudo apt-get install python-setuptools python-dev build-essentialsudo easy_install pipsudo pip install sphinxjp.themes.basicstrapsudo pip install sphinx_bootstrap_theme

Working from your Mac or Windows, these files can be downloaded through git. When sphinx is installed, it automat-ically updates python.

Sphinx install directions: http://www.sphinx-doc.org/en/stable/install.html#mac-os-x-install-sphinx-using-macportsSphinxjp.themes.basicstrap: https://github.com/tell-k/sphinxjp.themes.basicstrap Sphinx_bootstrap_theme:https://pypi.python.org/pypi/sphinx-bootstrap-theme/

Now we need to change our theme to basic strap and choose from one of the options available on this website:

https://pythonhosted.org/sphinxjp.themes.basicstrap/index.html

It has a very nice interactive viewer so you can decide which one you prefer.

I have chosen the “superhero” theme, so my websites can have superpowers. You can substitute “superhero” belowwith your preferred theme name from bootswatch.

25

http://www.sphinx-doc.org/en/stable/install.html#mac-os-x-install-sphinx-using-macports

https://github.com/tell-k/sphinxjp.themes.basicstrap

https://pypi.python.org/pypi/sphinx-bootstrap-theme/

https://pythonhosted.org/sphinxjp.themes.basicstrap/index.html


26 Chapter 10. MAKING OUR DOCUMENTS LOOK NICE

CHAPTER 11

Changing the Theme on the Local Computer or Remotely on the EC2

Choose this option if you want to create html pages on your computer for upload to a url that you own, or to previewthe look of a page once it gets transferred to readthedocs.org via githbub or bitbucket.

nano ~/Tutorial/source/conf.py

Find the html_extensions line and replace the one line with two:

#html_theme = 'default'extensions = ['sphinxjp.themes.basicstrap']html_theme = 'basicstrap'

Scroll down to the next paragraph, uncomment the html_theme_options and put the desired style in to the text.

#html_theme_options = {}html_theme_options = {

'inner_theme': True,'inner_theme_name': 'bootswatch-superhero',

}

Let’s rebuild our webpage and take a look at it now.

cd ~/Tutorialmake html

Open your local html file or bring your new html to the desktop by scp from the remote EC2 instance. This has to bedone from your local terminal to work. Open a new terminal window separate from your EC2 instance and do not loginto the EC2 instance before running this command. This is easier to do on a Windows machine if you have OpenSSHor another terminal program already installed.

Example for scp:

scp -i ~/Desktop/reST.pem [email protected]:/Tutorial/* ~/Desktop/

You will need to specify the location of your .pem file and your instance address.

Webhooks and Automation

27


28 Chapter 11. Changing the Theme on the Local Computer or Remotely on the EC2

CHAPTER 12

Webhooks and Automation

Now that we have created an appealing format to our website, we are ready to automate the process.

One way to automate the building of a website is to take advantage of freely available websites called “git repositories”that allow collaborators to share code/text/images in a simple to use format. Github and bitbucket are just two of thesepublicly available repositories. Each repository has their own quirks. I prefer bitbucket because I can easily create awebhook that matches one of the bootswatch formats with just a few additional steps. Also, many of my collaboratorsare on bitbucket. Github is nice as well, because it has added many user friendly features such as drag and drop for fileuploading from a desktop (useful for this tutorial) and allows for the creation of webpages by simply adding a branchcalled “gh-pages”.

29


30 Chapter 12. Webhooks and Automation

CHAPTER 13

Create a Repository

You do not have to do this twice, it is okay to pick one or the other. Ask your collaborators which one they prefer, it isoften easier to share within a repository than across them for general maintenance and lack of duplication.

bitbucket.org github.org

In order to communicate with your remote repository, you may need to add git to your local computer.

Windows git: https://git-scm.com/download/win

Mac git: http://git-scm.com/download/mac

Create a file directory to hold your repository.

mkdir local/repo/foldercp myfile.rst local/repo/folder/

If you didn’t complete the earlier tutorial, you can get some example rst text here:

http://www.southampton.ac.uk/~fangohr/computing/rst/rst.txt

Copy and paste the text into myfile.rst. You can either use nano or the web interface to create files from scratch. Notall the links will work, since we only borrowed the text and not the images.

Once you create your repository folder on your local computer, copy your .rst file into that location and push it to therepository. You also want to create a simple README.rst file to describe the repository.

For example:

nano README.rst

=========================================Example ReStructuredText (rst)=========================================

This is my project, created this day.

************Author

************Your name

Please contact me at my github/bitbucket account, here are the details.....

Control-X to close the file

31

https://git-scm.com/download/win

http://git-scm.com/download/mac

http://www.southampton.ac.uk/~fangohr/computing/rst/rst.txt


13.1 Bitbucket version

If you need to create a repository on bitbucket, got the top of the page (after signing in) and choose the dropdown tab“repositories”. Select “create a repository” and follow the instructions.

Uncheck private repository when setting this up, or else you won’t be able to webhook to readthedocs.org .. ..

cd local/repo/folder/git initgit remote add origin [email protected]:yourbitbucketname/yourrepository.gitgit add myfile.rstgit add README.rstgit commit -m 'Sending myfile.rst and README.rst to the remote repository'git push origin master

13.2 Github version

Github also has a dropdown box you can find by going to your profile (click on the avatar in the upper right or chooseyour name at the top of any github page). Choose the green “New” button, and make sure to keep the repository publicas you create it. .. ..

cp myfile.rst local/repo/folder/cd local/repo/folder/git initgit remote add origin https://github.com/yourgithubname/yourrepository.gitgit add myfile.rstgit add Readme.rstgit commit -m 'Sending myfile.rst and README.rst to the remote repository'git push origin master

Check your remote bitbucket or github to see if the file appeared. If it is not working from your local computer,you can always create files in the web browser. Just remember to “commit” after making any changes in those filesonline. If you make changes online before you do locally, make sure to do the following to bring those updates to yourcomputer.

git pull origin master

If you make any changes locally remember to commit and push them to the remote repository.

git commit -m 'I changed my README.rst file'git push origin master

Once a file has been added, you don’t need to add it a second time to make changes. As long as you don’t change thename of the file, git can track any changes you have made. However, the local and remote repositories don’t talk toeach other automatically, so remember to do those git pushes and pulls to keep your edits up to date.

Before we move on, make sure you have the following two files in your remote git repository:

README.rstmyfile.rst

And, any other files you have added.

32 Chapter 13. Create a Repository

CHAPTER 14

Readthedocs.org

Both github and bitbucket allow “webhooks” with readthedocs.org. A webhook recognizes when you have made achange to your git repository and automatically updates the website at readthedocs.org. Website naming is based onyour project, so it is easy to create website names that match your project. However, if someone has taken that namealready, it is not so easy to claim it. However, readthedocs.org regularly removes unused and untended webpages, sounused page names become available on a regular basis.

In order to complete the next part of the tutorial, please sign up for a free account at readthedocs.org.

After signing up, make sure readthedocs can find your bitbucket and github repositories.

Find the upper right tab on the readthedocs page, and select “settings” in the dropdown box. Select the second tab inthe middle of the page, labeled “Connected Services”. Once you click on that tab, buttons for github and bitbucketwill appear at the bottom of the page. I have both set up on my account, since I publish websites sourced from bothrepositories. :: ::

.. image:: images/rtdsettings.png

width 500 px

align center

Click on the profile tab in the upper right corner, choose projects from the dropdown tag. Find the import button atthe top of the list of projects and click on it. The import list will look for any repositories that you have linked toreadthedocs.org

33


Pick one and import it into readthedocs.org. Leave all settings the same as the default.

images/rtddefaults.png

Note that before the build, there is a notice on the right side that says “No builds yet”.

The Project Privacy Level is public.

34 Chapter 14. Readthedocs.org


Click on the “Build” button in the middle of the screen.

You should see a table that tells you how your project is proceeding. If you click on the “Triggered”, “Passed” or“Failed” notice, it will show details of progress.

35


After the build is finished, click on the green “View Docs” button in the upper right corner.

If you see a mistake on the page, you can go directly to github or bitbucket by clicking on the link. Every time youmake an adjustment, readthedocs.org will read it and update the page.

Try that now – go to your git repository and make a change. After you return to readthedocs.org, make sure to go toyour repository overview page and rebuild the document.



You will probably get this error, since we have not created a file called “index.rst”.

This is a new bug I recently (Feb. 2016) noticed with readthedocs.org webhooks. It will not recognize a README.rst,it is looking for an index.rst. This is similar to the front page of website.

Let’s make an index.rst and have it point at our other two files. In our local directory we can use our text editor, or doit directly from command line. Or, we can open a file on the website of our repository directly.

nano index.rst

.. toctree:::maxdepth: 2:numbered::titlesonly::glob::hidden:

README.rstother.rst

###################My project's index###################

If your are lost, here is where to start: :doc:`README`

You can find more information at :doc:`other`

37


Control-X to close the file

Return to readthedocs.org overview page for your project and click “build”.

This looks more reasonable. We now have some navigation options on the side bar and inside the body of the textitself.


CHAPTER 15

Automating the Web Hook

Until now, we have been manually returning to the readthedocs.org page to click on the build button after every changein our repository. There are two steps we can take to automate the process. Because Readthedocs.org is so popular, itis listed as one of the webhooks already offered as a service in both of the repositories we are using for our documents.

Find the settings page inside your repository.

On the left side of the page, choose the Webhooks & services tab.

39


In the bottom box, choose “Add Service” and drop down to Read the Docs.

On the left side of the page, choose the Webhooks & services tab.

Press the “Add Service” button.

Every time you update your git from now on, it will trigger a build in readthedocs.org.

40 Chapter 15. Automating the Web Hook


Try it. Change something and check the result.

The process is very similar.

This time, the setting can be found on the lower left side of your repository page. It is a little wheel.

When the next page opens up, find the Services tag under integration, and look for Read the Docs in the dropdownbox.

41


Follow this link to discover how to add sphinx style sheets to readthedocs.org pages:

Changing the style pages for Read the Docs

42 Chapter 15. Automating the Web Hook

CHAPTER 16

Changing the style pages for Read the Docs

Most readthedocs.org pages look very similar, because until recently, there hasn’t been an easy tool for updating stylesheets.

43


44 Chapter 16. Changing the style pages for Read the Docs

CHAPTER 17

In Summary

By harnessing the power of git repositories, the creation of a nice website can be automated with just a few changes ina git repository.

Make sure Read the Docs service is turned on for your repository. Webhooks and Automation

17.1 Set up Read the Docs

Create a requirements.txt file inside your repository (either with a text editor, nano on the command line or directlythrough the web interface).

Past the following into the requirements.txt file.

https://pypi.python.org/packages/py2.py3/p/pip/pip-8.0.3-py2.py3-none-any.whl#md5=b234250205337ff67967dff300001e3dhttps://pypi.python.org/packages/2.7/S/Sphinx/Sphinx-1.3.5-py2.py3-none-any.whl#md5=ee41d9921df3f251bff900a60d608f9bhttps://pypi.python.org/packages/2.7/P/Pygments/Pygments-2.1-py2-none-any.whl#md5=cc82b28005bae9b0e13c95afbe2ec1bcsphinx-rtd-theme==0.1.8sphinxjp.themes.basicstrap==0.4.3

Push the requirements.txt file into your repository.

Next, go to the readthedocs.org website for your project.

Find the Admin button on the overview page for your repository. In this case, it is the button all the way to the right.

45


17.1.1 Open the advanced settings tab.

Complete two tasks. Check the box that says “Install your project inside a virtualenv using setup.py install”

In the box below that, put “requirements.txt” for the requirements file.

Submit your changes (the button is at the bottom of the page).

46 Chapter 17. In Summary


Add the configuration file, conf.py from the MAKING OUR DOCUMENTS LOOK NICE exercise to your repository,as well as all the style sheets (the entire source and build files).

When you copy the conf.py file, don’t forget to change the following:

master_doc = 'index'

In addition to the previous conf.py edits from the :doc: Style_Sheets exercise.

Finally, git push all the style sheet information from the desktop sphinx build for this page.

git add, git commit, git push from the command line also works well.

Github has a convenient drag and drop feature for this, if the command line version of git is still a challenge.

17.1. Set up Read the Docs 47


48 Chapter 17. In Summary

CHAPTER 18

Restructured Text for Building Webpages for Git Repositories

Part of the Data Intensive Biology Training program, UC Davis http://dib-training.readthedocs.org/en/pub/

Instructor: Adelaide Rhodes, Ph.D., Oregon State University, Center for Genome Research and Biocomputing

18.1 Description:

This class will walk through the creation of webpages that can be linked through bitbucket or github as well as on yourown personal server. The first part of class will provide basic syntax for reStructured Text for developing webpages.The second part of the class will use Sphinx for html conversion into indexable webpages with many options. Thethird part of the class will discuss how to put the webpage up on readthedocs.org via webhooks from a bitbucket orgithub account.

18.2 Learning Objective:

• The ability to create webpages in a matter of minutes without a lot of confusing syntax

• The conversion of reST to webpage readable formats through an intermediary program such as sphinx

• The ability to link content to a live url via a github or bitbucket account

18.3 Webtools to Sign up For Beforehand

• A github or bitbucket account (both free) will allow you to put your website up. Github is more intuitive forbeginners, bitbucket is prettier

• A readthedocs.org account (also free)

• An amazon account to access the EC2 instances (we will only be using free options)

For the tutorial on reStructured Text, I recommend having a good text editor on your computer:

18.3.1 Windows:

I recommend Notepad++ or Sublime3 for Windows. TextEdit is okay, in windows, but does not have the nice format-ting options of Notepad++. Sublime3 automatically recognizes and colorcodes several programming languages.

49

http://dib-training.readthedocs.org/en/pub/


18.3.2 Windows Text Editors:

• https://notepad-plus-plus.org/download

• https://github.com/atom/atom/releases/download/v1.5.3/atom-windows.zip


18.3.3 MacOSX:

I recommend Atom or Text Wrangler for Mac. Atom has the added function of being able to preview certain typesof markdown (not reST) in an adjacent window and will allow direct edits to a github repository within the program.Text Wrangler allows files to be saved in Unix-code directly, and has a spellchecker built in.

• https://s3.amazonaws.com/BBSW-download/TextWrangler_5.0.2.dmg

• https://atom.io/


The most important feature is to have a text editing tool that does not add back-end coding (e.g. Microsoft Word) andthat has line numbering along the side. This will be important later when Sphinx builds the Makefile.

18.3.4 OPTIONAL DOWNLOADS

We will be reinterpreting our reST into html using sphinx and/or pandocs. These tools can be downloaded to yourlaptop, but to facilitate the tutorial, we are actually going to open and run instances on Amazon EC2. Please read thisinformation beforehand: http://angus.readthedocs.org/en/2015/amazon/index.html

In order to use the EC2 instance, it will be necessary to have a good windows terminal program installed, such asPutty. Also, an scp tool such as WinScp would be helpful for data transfer between the EC2 and your laptop.

If you would prefer to work from your desktop, here are the download links for sphinx:


Sphinx is a python module, so python will need to be be installed as well.

50 Chapter 18. Restructured Text for Building Webpages for Git Repositories

https://notepad-plus-plus.org/download

https://github.com/atom/atom/releases/download/v1.5.3/atom-windows.zip


https://s3.amazonaws.com/BBSW-download/TextWrangler_5.0.2.dmg

https://atom.io/




Sphinx, Webhooks, and Bitbucket Documentation

Documents

Transcript of Sphinx, Webhooks, and Bitbucket Documentation