Sphinx, Webhooks, and Bitbucket Documentation Release 1.0 Adelaide Rhodes, Ph.D. March 30, 2016 Contents 1 Introduction 1 2 Start of the Tutorial 3 2.1 Paragraph.................................................3 2.2 Inline markup...............................................4 2.3 Lists...................................................5 2.4 Pre-formatted text............................................6 2.5 Section Headers.............................................6 3 Introduction - “Chapter I” 9 4 Start of the Tutorial - “Chapter II 11 4.1 Paragraph - Section............................................ 11 4.2 Inline markup - Section......................................... 11 4.3 Document titles and subtitles....................................... 11 4.4 Copy and Paste your page into the following website to check your syntax:.............. 12 4.5 Correct any errors that you can see.................................... 12 4.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 31 13.1 Bitbucket version............................................. 32 13.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 45 17.1 Set up Read the Docs........................................... 45 18 Restructured Text for Building Webpages for Git Repositories 49 18.1 Description:............................................... 49 18.2 Learning Objective:........................................... 49 18.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 to produce “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 in frustration 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 before and 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 types of 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) and that 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 Text Wrangler 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/ • https://www.sublimetext.com/3 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 Sphinx, Webhooks, and Bitbucket Documentation, Release 1.0 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 the name. 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 found underneath 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 Sphinx, Webhooks, and Bitbucket Documentation, Release 1.0 2.3 Lists Three kinds: 1. enumerated, * bulleted, and definitions 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 by parentheses “( )” 1. numbers 1. upper-case letters. Information can be continued over several lines, to create a new paragraph, make sure to leave 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 Sphinx, Webhooks, and Bitbucket Documentation, Release 1.0 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 to the 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 indicate that 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 block will 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 can just 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 this document. 6 Chapter 2. Start of the Tutorial Sphinx, Webhooks, and Bitbucket Documentation, Release 1.0 • Sections can be indicated by the following: = - ‘ : ‘ ” ~ ^ _ * + # < > • The underline symbol must extend as long as the text, and appear immediately underneath the name of the section • 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 remember which symbols you used for each level.