AAAAAA DocumentationRelease 0.4.0

alnoki

Mar 21, 2019

Getting started

1 Alnoki’s Algorithmic Analysis Asset Allocation Applications (AAAAAA) 11.1 What are they? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 Python? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

2 Getting started 32.1 Quickstart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42.3 What next? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

3 User guide 73.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73.2 Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

4 Developer guide 114.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.2 Environment setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124.3 Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.4 Distributing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464.5 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484.6 Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

5 Indices and tables 775.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775.2 Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775.3 Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785.4 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Bibliography 107

Python Module Index 109

i

ii

CHAPTER 1

Alnoki’s Algorithmic Analysis Asset Allocation Applications (AAAAAA)

Brought to you by alnoki

1.1 What are they?

AAAAAA Alnoki’s Algorithmic Analysis Asset Allocation Applications (AAAAAA or double-triple Alfa), collo-quially referred to as alnoki’s apps, are a growing collection of financial analysis software tools. Source codeis written in the Python computer language, and uses packages that have been developed by the open-sourcecommunity

1.2 Python?

You can use a bit of Python on most computers with minimal effort, using print():

1. Start the command line on your computer:

Operating System Command lineLinux TerminalMac TerminalWindows Command Prompt

1. Type python then type return

1. If this doesn’t work then you probably don’t have Python, but you can get it for free !

1. Download Miniconda

2. Start up Conda

3. Type python then type return

• Rejoice, for you have just started the Python interpreter

1

AAAAAA Documentation, Release 0.4.0

2. Copy and paste the below contents to the command line then type return:

print("I am a computer programmer!")

3. If you are feeling fancy:

for i in range(5):print("Please be aware of the number", i)

• This Python input ends with a line of code that is indented, so type return twice after copy-pasting theabove contents

4. How about some factorials? The “factorial of 𝑥” is given by:

𝑥! = 𝑥(𝑥− 1)(𝑥− 2) . . .

More eloquently:

𝑥! =

⎧⎪⎨⎪⎩1 𝑥 = 0𝑥∏︁

𝑘=1

𝑘 𝑥 > 0

factorial = 1 # Initialize factorialfor x in range(10):

if x > 0:factorial = x * factorial # Update factorialprint("Please be aware of the number", x,

"with factorial", factorial)

Don’t forget

This Python input ends with a line of code that is indented, so type return twice

Congratulations!!!

Tip: If you are viewing this as a website, then click the Next button at the top or the bottom of this webpage to beginyour journey

2 Chapter 1. Alnoki’s Algorithmic Analysis Asset Allocation Applications (AAAAAA)

CHAPTER 2

Getting started

Here is where the AAAAAA journey begins!

2.1 Quickstart

If you want to try out some basic AAAAAA functionality, then follow the below steps:

1. Download Miniconda (a variant of Anaconda), which will give you quick access to Python if your operatingsystem did not come with Python

2. Download the AAAAAA repository archive

3. Start up conda in the root directory of the archive you just downloaded

4. Type python then type return

• Rejoice, for you have just started the Python interpreter

5. Copy and paste the following then type return

import datetime # Lets you work with dates and timesimport decimal # Lets you work with $$.¢¢from src.AAAAAA.ledger import Transaction # From AAAAAA codebasemy_transaction = Transaction(

when=datetime.date(1994, 6, 19), total_amount=decimal.Decimal('24.48'),kind='Buy', symbol='ALNOKI', num_shares=12)

6. You just paid 24 dollars and 48 cents for 12 shares

my_transaction.per_share_amount # How much does each one cost?

Congratulations!!!

3

AAAAAA Documentation, Release 0.4.0

Tip: If you are viewing this as a website, then click the Next button at the top or the bottom of the webpage tocontinue

2.2 Examples

Coming soon

2.3 What next?

Which of the following describes you?

• You have no idea what is going on

• You don’t want to get sidetracked

• You are curious about using the software

• You want to make a website or a software package like this

• You want a list of references, terms, and versions

• You would like to view this in a different format or version

2.3.1 You have no idea what is going on

You are in the right place! AAAAAA require no specialized background knowledge, so keep on clicking next (if, ofcourse, you are viewing this as a website)

Information is usually accompanied by a relevant Uniform Resource Locator (URL), also known as a link, for awebpage from somewhere like Python.org, Wikipedia, or YouTube. Typically this information is accompanied by aconceptual explanation that fits within the context of AAAAAA

You will soon learn that AAAAAA live within the magical, open-source world of Python. Indeed, you shall learn thatwhich you need as you follow the next-lit path that has befallen you in AAAAAA (if, of course, you are viewing this asa website)

Otherwise, keep reading!

2.3.2 You don’t want to get sidetracked

Keep on clicking next (if, of course, you are viewing this as a website)! Lucky for you, this website is made withSphinx and as such you can view every webpage in a logical linear order without having to think twice (if you usenext)

Otherwise, keep reading!

4 Chapter 2. Getting started

AAAAAA Documentation, Release 0.4.0

2.3.3 You are curious about using the software

Head on over to the user guide! It is accompanied by examples of Python concepts that will clarify the use of AAAAAAfor security analysis

2.3.4 You want to make a website or a software package like this

If you want to know how AAAAAA are made, how this website is made, or how to re-create the development environ-ment that alnoki uses, head over to the developer guide

2.3.5 You want a list of references, terms, and versions

Check out the indices!

2.3.6 You would like to view this in a different format or version

Documentation for AAAAAA as a website can be accessed via the URL provided at the AAAAAA repository. This isthe preferred method for learning about AAAAAA

Once you are at the website, you can access the PDF or a different version by opening up the sidebar then clickingRead the Docs button

2.3. What next? 5

AAAAAA Documentation, Release 0.4.0

6 Chapter 2. Getting started

CHAPTER 3

User guide

Here you can learn to use AAAAAA!

3.1 Introduction

If you haven’t already taken a look at the examples section, which showcases select AAAAAA functionality, you maywant to start there

This guide explains, with more depth than the examples section, the various Python and finance concepts associatedwith AAAAAA, while presenting a closer look at the source code. You do not need any background knowledge onPython or software in general, as this guide is designed to teach you all that you need to know in order to use AAAAAA.Concepts are presented in a logical sequence (as long as you keep clicking Next!) that is designed to be self-contained,but if you want more resources there a few select ones below

Table 1: Select references within AAAAAAReference TopicPython Conceptual explanationExamples Demonstrations

Table 2: Select referencesReference TopicCorey Schafer tutorials Learn Python (recommended)The Python Tutorial Official tutorial

Tip: Keep on clicking the Next button at the top or the bottom of the webpage! It will allow you to sequentially visitall webpages of documentation for AAAAAA in a logical order

7

AAAAAA Documentation, Release 0.4.0

3.2 Transactions

• Background financial info

• Mechanics

• A word (or several) about precision

– Okay, alnoki is fired up

3.2.1 Background financial info

A brokerage facilitates the buying or selling of securities, which are tradable forms of financial assets. One exampleof a security is a share of stock, which represents fractional ownership of a corporation

Typically, a ticker symbol will be used to identify the particular security that is the subject of a financial transaction

Securities are typically transacted for a medium of exchange, like money, and AAAAAA measure money using units ofUnited States dollars (USD) and cents:

Table 3: Money notation in AAAAAAUnit SymbolUSD $Cents ¢

3.2.2 Mechanics

AAAAAA.ledger.Transaction, shortened to Transaction, is a class, which is a special type of object:

class AAAAAA.ledger.Transaction(when: datetime.date, total_amount: decimal.Decimal, kind:str, symbol: Optional[str] = None, num_shares: Optional[int]= None, description: Optional[str] = None)

A financial transaction

whenTime of occurence

Type datetime.date

total_amountThe amount of money involved, in units of $ and ¢

Type decimal.Decimal

kindWhat kind of transaction

Type str

symbolAssociated ticker symbol

Type str or None

num_sharesNumber of associated shares

8 Chapter 3. User guide

AAAAAA Documentation, Release 0.4.0

Type int or None

descriptionA description, typically provided by a brokerage

Type str or None

kindsAllowed kinds of transactions

Type set of string

per_share_amountThe amount of money associated with each share

Only defined if num_shares is defined and is nonzero

Type decimal.Decimal or None

Tip: If you are viewing AAAAAA documentation as a website, you can click [source] above to view the originalsource code, then click [docs] to return

Transaction has a namespace with various attributes, like total_amount or symbol

kinds is a class variable that describes the possible values that can be assumed by kind, which is an instancevariable

Table 4: Possible kindsKind Ticker symbol associated? Interpretation'Bank transfer' No Add money from a Bank'Buy' Yes Pay money for a security'Dividends' Yes Receive money from a security'Fees' Yes Pay a fee when selling a security'Sell' Yes Sell a security for money

When you initialize an instance of Transaction you are calling a function and as such you must provide defaultargument values, also known as positional arguments, like total_amount

You may optionally provide one or more keyword arguments, like num_shares, for example, which would enableyou to access per_share_amount, (itself a property)

3.2.3 A word (or several) about precision

Clearly you need to work with numbers, and it makes sense to have an integer amount of shares

But does it make sense to buy something that costs exactly $110.1200000000000045474735088646411895751953125?!?!?!?

This just in

No, it does not!

That is why total_amount is a decimal, not a floating point number

3.2. Transactions 9

AAAAAA Documentation, Release 0.4.0

Okay, alnoki is fired up

You bet your bottom dollar (USD) that alnoki is on a floating point precision rampage

If you don’t already know how invoke the Python interpreter, please feel free to to grab yourself a slippery new copyof Miniconda and fire up conda then type

python

Type return and take several deep breaths to calm your nerves, but don’t take too many stabilitory inhalations oryou may deviate from the pressing inquisition on hand, which continues below

Tip: Copy-paste the below lines into the Python interpreter then type return

from decimal import DecimalDecimal.from_float(110.12)

What’s that you say, Python interpreter?

>>> from decimal import Decimal>>> Decimal.from_float(110.12)Decimal('110.1200000000000045474735088646411895751953125')

See also:

The official floating point precision rampage

10 Chapter 3. User guide

CHAPTER 4

Developer guide

Here you can learn to create AAAAAA!

4.1 Introduction

• How alnoki’s apps are made

• How you can make something similar

4.1.1 How alnoki’s apps are made

The environment setup will help you install the tools and configurations that alnoki uses to create AAAAAA

The concepts section provides concise conceptual explanations of the tools and configurations that alnoki uses tocreate AAAAAA, and the specific ways that they are used

The distributing section contains detailed explanations to guide you through distributing your documentation and(coming soon) more

The testing section is coming soon

The procedures section contains checklist-like instructions for common development tasks, like managing referenceswith Sphinx

Tip: Keep on clicking the Next button at the top or the bottom of the webpage! It will allow you to sequentially visitall webpages of documentation for AAAAAA in a logical order

11

AAAAAA Documentation, Release 0.4.0

4.1.2 How you can make something similar

Everything you should need to know about how AAAAAA are developed is explained in the following sections, butif you are just looking for some quick information on starting your own Sphinx-style website, which you can indeedhave hosted for free, some select links are below

Table 1: How alnoki does itReference TopicDocumentation Guide to distributing

Table 2: Start your own Sphinx-style website, for freeReference TopicRead the Docs with Sphinx Hosting platform integrationQuickstart tutorial Starting a blank Sphinx project

Of course there are a few things you will need to figure out along the way, but documentation for AAAAAA can helpwith that. And don’t forget, there’s always Google

4.2 Environment setup

The steps in this section will enable you to reproduce the integrated development environment that alnoki uses tocreate AAAAAA, which will all be explained afterwards in the concepts section

Before you begin, you will need Miniconda, which will give you access to Python and Anaconda. If you participatedin the quickstart, then you should already have Miniconda

Any tools and configurations that you might need will be downloaded throughout the following instructions, so getready to install some free software!

4.2.1 Documenting

1. Download VS code and get ready for some extensions

2. Install the VS Code Bookmarks extension

3. Update the VS Code integrated terminal USER SETTINGS in settings.json so that you can use conda:

• On a Mac, add the following options so you can use bash login mode invocation:

{"terminal.integrated.shell.osx": "/bin/bash","terminal.integrated.shellArgs.osx": [ "-l" ],

}

• On Windows, use the /K cmd.exe option so you can use Anaconda Prompt (adapted for your usernameand computer):

{"terminal.integrated.shell.windows": "C:\\Windows\\System32\\cmd.exe","terminal.integrated.shellArgs.windows": ["/K",

(continues on next page)

12 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

(continued from previous page)

→˓"C:\\Users\\alnoki\\AppData\\Local\\Continuum\\miniconda3\\Scripts\\activate.→˓bat"],}

Note: Be sure to copy and paste the whole box! It may scroll to the right

4. Use the VS Code Command Palette to open a new integrated terminal and copy and paste the following com-mand to create a new conda environment, called a6, that has the necessary packages:

conda create --name a6 python conda pep8 sphinx sphinx_rtd_theme

5. Configure the integrated terminal to automatically activate the a6 environment:

• On a Mac, there is no bash equivalent to the /K cmd.exe option, so the easiest way to activate the a6environment is to add the following to ~/.bash_profile, which will execute any time a bash login modesession starts (even outside of the integrated terminal):

# Activate a6 conda environment when bash login session startsconda activate a6

• On Windows, append "a6" to the "terminal.integrated.shellArgs.windows" setting fromabove:

{"terminal.integrated.shellArgs.windows": ["/K",

→˓"C:\\Users\\alnoki\\AppData\\Local\\Continuum\\miniconda3\\Scripts\\activate.→˓bat",

"a6"],}

6. Install the VS Code Python extension and use the Command Palette to select the intepreter for a6

• This should add a setting for your computer-specific path to settings.json. If it is added to WORKSPACESETTINGS in settings.json, make sure to put it in USER SETTINGS instead

• On a Mac, this should look like:

{"python.pythonPath": "~/miniconda3/envs/a6/bin/python"

}

• On Windows, this should look like:

{"python.pythonPath":

→˓"C:\\Users\\alnoki\\AppData\\Local\\Continuum\\miniconda3\\envs\\a6\\python.→˓exe",}

• You can also get this path by activating the a6 evironment then typing which python

7. Use the integrated terminal to install a few more packages that come from the conda-forge:

4.2. Environment setup 13

AAAAAA Documentation, Release 0.4.0

conda install -c conda-forge doc8 sphinxcontrib-bibtex sphinx-autobuild

8. Install the VS Code reStructuredText extension

9. If you don’t already have it, download Git

• To figure out if you have it, open the integrated terminal and type:

git --version

10. Install the VS Code GitLens extension

11. Use the Command Palette to git-clone the AAAAAA repository

• This will include all of the VS Code settings that alnoki uses

12. At this point you should be able to build the documentation and play around with the reference managementfeatures

Congratulations!!!

4.2.2 Analyzing

1. Use the VS Code integrated terminal to install some more conda packages for a6:

conda install jupyter numpy matplotlib pandas

2. Install the Unofficial Jupyter Notebook Extensions:

conda install -c conda-forge jupyter_contrib_nbextensions

3. Open a Jupyter Notebook:

jupyter notebook

4. Click Nbextensions, and enable the following extensions:

1. Collapsible Headings

2. Table of Contents (2)

• Select Add a Table of Contents cell at the top of the notebook

3. Variable Inspector

4. Live Markdown Preview

Congratulations!!!

4.2.3 Testing

1. Use the VS Code integrated terminal to install some more conda packages for a6:

conda install pip pytest

2. From inside the AAAAAA project directory, configure pytest discovery for AAAAAA:

pip install -e .

14 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

3. Install the Python Test Explorer for VS Code

4. Tidy up:

conda update --allconda clean --allconda list

Note: Copy-paste this one line at a time

5. Try out pytest from inside the AAAAAA root directory:

pytest

Congratulations!!!

4.2.4 Contributing

Disclaimer

If you already have experience developing, you might have some preferences of your own which involve differentprocedures. That’s okay, but the below information is still included as a reference

Git

If you want to contribute to AAAAAA, then you will need to do a bit more setup for Git. It is recommended that youfirst review the remainder of the developer guide before you begin

The Git configuring procedures will help you get started, and the rest of the Git procedures describe some commondevelopment tasks that enable online collaboration

Make sure to follow Git commit guidelines, and review the Tools: Git section if you want more information

Vim

To maximize efficiency, install the Vim extension for VS Code. If you have never used it before, the Tools: Vim sectionhas plenty of references that can help you learn

4.3 Concepts

All of the tools used to create AAAAAA are free, and most are open-source. If you completed the developer environmentsetup then you will have just finished downloading all of them

• Tools describes the core concepts of things like Git and Sphinx, but not precise AAAAAA use cases. Rather,information in tools provides links to procedures or other specific instructions

• Project structure describes the contents of the AAAAAA repository and provides links that help describe theindividual components contained therein

• Documentation describes the file structure of contents related to Sphinx and Jupyter, and provides syntax guide-lines

4.3. Concepts 15

AAAAAA Documentation, Release 0.4.0

• Configurations describes the VS Code settings (and more!) that you downloaded during the developer environ-ment setup, and how they affect tools that are used for the development of AAAAAA

• Code describes the file structure of contents related to Python source code and pytest test code, as well as somesyntax guidelines

4.3.1 Tools

• The Holy Grail

– Google

• Core

– Python

– Anaconda

– Git

– VS Code

– Vim

• Documentation

– Sphinx

– reStructuredText

– Read the Docs

– Sphinx extensions

* Included with Sphinx

· Intersphinx

· Napoleon

· extlinks

* Not included with Sphinx

· xref

· BibTeX

– sphinx-autobuild

• Analysis

– Jupyter

– Numerical conda packages

• Testing

– pytest

• Distributing

– PyPI

16 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

The Holy Grail

Google

This is by far the most important tool that alnoki uses

Nearly everything that alnoki has done to create AAAAAA has started with searches on Google. Because so manycomponents of AAAAAA are open-source software, the primary means of accessing them is the Internet, which Googlehas done a remarkable job of indexing. With the exception of a few books (which are likely on the Internet, too), allthe information you see here is free, and you can find it with Google

It is not an exaggeration to say that you can legitimately figure out all of this for yourself with a laptop, access toGoogle, and enough curiosity. That is of course, how alnoki did it, after all

Core

• Python

• Anaconda

• Git

• VS Code

• Vim

Python

Python is an open-source computer language with various applications. The source code for AAAAAA is written inPython, using assorted packages. See the examples section for a showcase of AAAAAA functionality

The AAAAAA user guide teaches Python as it describes various features of AAAAAA. The code concepts sectiondescribes some additional specific Python considerations in AAAAAA like syntax and directory structure

Table 3: Select references within AAAAAAReference TopicDeveloper environment SetupCode concepts Syntax and file structureUser guide Walkthrough

Table 4: Select referencesReference TopicPython.org Official informationCorey Schafer tutorials Learn Python (recommended)The Python Tutorial Official tutorialFunctional Programming HOWTO Function techniquesPython HOWTOs Specific use casesPython Frequently Asked Questions Common issuesProgramming FAQ Advanced technical informationThe Python interpreter Executes any source code in Python

4.3. Concepts 17

AAAAAA Documentation, Release 0.4.0

Anaconda

Anaconda contains a collection of Python packages that are free to download and use. The base Anaconda collectionhas way more Python packages than AAAAAA require, so you can use Miniconda to access only the ones that you need

You can manage these packages using conda, a command line utility that automatically maintains compatibility be-tween packages. Conda packages can be downloaded from different conda channels, like the conda-forge

Table 5: Select references within AAAAAAReference TopicDeveloper environment SetupConda procedures UsageConda configuration Options

Table 6: Conda referencesReference TopicConda Official referenceManaging environments Official practical referenceConda cheatsheet Common commands for condaMiniconda URL for download

The developer environment setup describes how to create a new conda environment, called a6, which you can alsoreproduce via the import a6 procedure

a6 A conda environment containing all the packages that AAAAAA require during development

Table 7: Conda packages required for AAAAAAPackage Function Setup Phase ChannelPython Source code creation Documenting condaconda Package management Documenting conda

PEP 8Linter for code style Documenting conda

Sphinx Build documentation Documenting condaRTD Sphinx Theme Documentation appearance Documenting condaDoc8 reST linter Check documentation style Documenting conda-forgeBibTeX Book citations Documenting conda-forgesphinx-autobuild Auto-update documentation Documenting conda-forgeJupyter Notebooks Interactive analysis Analyzing condaNotebook Extensions Enhance Jupyter Analyzing conda-forgeNumPy Number processing Analyzing condaMatplotlib Data plotting Analyzing condapandas Dataset management Analyzing condapip Enable testing Testing condapytest Code testing Testing conda

Git

Git is used manage changes to files in the AAAAAA repository. Git is a version control system that allows AAAAAAto be updated with commits, which are like snapshots in time that describe minor changes to AAAAAA. Each commitis identified by a Secure Hash Algorithm 1 (SHA-1) value, a unique identifier that can be accessed by viewing theproject log

18 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

Tags, which provide a unique identifier for commits, and branches, which enable independent sequences of commits,are used to manage project versions on GitHub, a free service that hosts the AAAAAA repository for free

There are several command line text manipulators that go along with Git

Table 8: Text manipulatorsTool UsageVim Configuring and Committingless Viewing project history

Table 9: Select references within AAAAAAReference TopicDeveloper environment SetupGit configuration OptionsGit procedures Usage

Table 10: Select referencesReference TopicGit manual Quick practical referenceGit book In-depth conceptual explanationsGit commit guidelines Contribution guidelinesDocumentation webhooks Automatic version supportVim text editor Official information

VS Code

Visual Studio Code is an integrated development environment (IDE) that is used to create AAAAAA, with additionalfunctionality provided by extensions

The AAAAAA repository comes with a collection of VS Code settings that will automatically configure most of yoursoftware workspace. If you completed the developer environment setup, then all the relevant configurations shouldalready be installed! These configurations will help with things like code style and test discovery. Additionally, thiswill configure your VS Code user interface with some select X11 colors

There is also the VS Code Insider Edition, which has all the latest features but may not be completely stable

Table 11: Select extensionsExtension Purpose Setup PhaseBookmarks Mark/navigate content DocumentingPython Using Python DocumentingreStructuredText12 Linter for reST DocumentingGitLens Advanced Git functionality DocumentingPython Test Explorer Using pytest TestingVim Efficiency Contributing

1 Requires a doc8 newline issue fix, included in the provided VS Code settings2 Offers rendering in real-time, but is not as reliable as using a browser with sphinx-autobuild. For example, fails for Intersphinx links

4.3. Concepts 19

AAAAAA Documentation, Release 0.4.0

Table 12: Select references within AAAAAAReference TopicDeveloper environment SetupVS Code configuration OptionsVS Code procedures Usage

Table 13: Select referencesReference TopicUser interface Official introductionPython integration Use Python with VS CodeCommand Palette Quickly input commandsSettings Official configuration optionsExtensions Additional functionalityIntegrated terminal Use a command line inside VS CodeVS Code unit testing pytest integrationMarkdown Planning version features

Table 14: Modifying colorsReference TopicThemes General usageColor theme extension guide Enhanced functionalityToken color customizations Official referenceToken colors with textMateRules Advanced usage

Vim

Vim text editor is an efficient way to manipulate files, but it can be tricky to learn. It is useful in command line-styleGit procedures and as a VS Code extension

If the below references are not enough, you may be surprised at the ability of a Google search to answer “how do I dooddly-specific thing x in Vim?”

Table 15: Select references within AAAAAAReference TopicVim configuration OptionsDeveloper environment SetupGit configuring procedures Command line usage

Table 16: Select official referencesReference TopicVim text editor Official informationOfficial tutorial Simple instructionsAll the right moves Intermediate command referenceMac OS syntax highlighting Enable syntax highlighting.vimrc file Configuration fileRepeating keystrokes Repeat commands

20 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

Table 17: Select referencesReference TopicMastering Vim Talk with tricks and tipsHow to Learn Vim How to learnInteractive Vim tutorial Learn interactivelyVim cheatsheet Common commandsVim E325 error Can happen when committing incorrectly

Documentation

• Sphinx

• reStructuredText

• Read the Docs

• Sphinx extensions

– Included with Sphinx

* Intersphinx

* Napoleon

* extlinks

– Not included with Sphinx

* xref

* BibTeX

• sphinx-autobuild

Sphinx

Sphinx is the documentation engine that builds the website for AAAAAA and even for Python itself. Sphinx usesreStructuredText (reST), a particular style of markup language, which is converted to HTML when building a website.Sphinx can also create a PDF of documentation

Sphinx has a table of contents feature (toctree), which provides a linearly navigable structure that ensures accessto all pages of documentation. AAAAAA are documented using the Read the Docs Sphinx Theme, which provides thevisual layout of this website

Sphinx extensions enable additional functionality and several are used in AAAAAA

4.3. Concepts 21

AAAAAA Documentation, Release 0.4.0

Table 18: Select references within AAAAAAReference TopicDeveloper environment SetupSphinx configuration OptionsreStructuredText Markup languageDocumentation structure Specific componentsSphinx procedures UsageSphinx extensions Extended functionalitysphinx-autobuild AutomationDistributing documentation Walkthrough

Table 19: Select referencesReference TopicSphinx Official documentationconf.py Official reference for configuration optionsBuilders Create different styles of documentationPython Developer’s Guide Python guide to using SphinxPractical use seminar Practical examples of proceduresReferences extension configuration example Related usage and configuration

reStructuredText

reStructuredText (reST) is a markup language containing syntax to generate fancy components like this, this, or t→ h → i → s

The two most fundamental reST components are the role, which marks a piece of text (usually in-line), and thedirective, which marks a block of text

Files that contain reST have an .rst extension, and Sphinx converts them to HTML whenever documentation is built

Table 20: Select references within AAAAAAReference TopicreST style StyleSphinx Documentation engineNapoleon Create E4s

Table 21: Select referencesReference TopicreStructuredText Primer Sphinx tutorial on reST usagereStructuredText Official documentationQuick reST Practical syntaxreST cheatsheet Quick syntax referenceRead the Docs sample project Sample syntaxDomains Application-specific roles and directives

Many Sphinx-style websites have an Edit on GitHub (or similar) feature at the top or bottom of each webpage. Thisfeature will link to the reST file that Sphinx used to create the webpage

22 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

Tip: You can harvest the syntax for nearly any kind of reST component from the Read the Docs sample project, viathe Edit on GitHub feature

After clicking Edit on GitHub, look for a Raw button, which should show you the reST

Read the Docs

Read the Docs is a free provider of hosting services for Sphinx projects, and even provides its own Sphinx Theme.Read the Docs uses webhooks to automatically detect any Git updates, which trigger new documentation builds. Readthe Docs also supports multiple versions of documentation

Documentation for AAAAAA uses the Read the Docs Sphinx Theme, which generates the visual appearance of thiswebsite. The theme even renders on the web browser for mobile devices!

Table 22: Select references within AAAAAAReference TopicRTD Configurations OptionsDistributing documentation WalkthroughDocumentation versioning Usage

Table 23: Select referencesReference TopicQuickstart tutorial Start a Read the Docs with Sphinx projectRead the Docs sample project Sample reStructuredText elementsWebhooks Automatic project modification detectionVersions Automatic version supportIntro to Sphinx and Read the Docs Introductory article for technical writers

Sphinx extensions

AAAAAA use some built-in Sphinx extensions and some that are not built-in

Table 24: Select references within AAAAAAReference PurposeDeveloper environment SetupSphinx Conceptual explanation

Table 25: Sphinx extensions in AAAAAAExtension PurposeIntersphinx Create links to other Sphinx projectsNapoleon Document code componentsextlinks Create links to common URLsxref Create links to arbitrary URLsBibTeX Cite books

4.3. Concepts 23

AAAAAA Documentation, Release 0.4.0

• Included with Sphinx

– Intersphinx

– Napoleon

– extlinks

• Not included with Sphinx

– xref

– BibTeX

Included with Sphinx

• Intersphinx

• Napoleon

• extlinks

Intersphinx

Intersphinx helps manage links to other Sphinx projects, via the Intersphinx procedures

Napoleon

Napoleon is a Sphinx extension that parses Python source code and creates documentation elements from docstringsand type annotations. It uses the same directives as autodoc, but it can accept NumPy docstrings. Napoleon andautodoc both convert docstrings into reST , like that used for info field lists

Docstrings are written using the Python domain, which is also used to reference Elaborately Embellished ExplanatoryEnhancements (E4) elsewhere in documentation

Table 26: Select references within AAAAAAReference TopicDocumentation syntax UsageNapoleon example UsageNapoleon procedures Usage

Table 27: Select conceptual referencesReference TopicNapoleon Official referenceDocstrings Comments for special source code componentsAutodoc Sphinx extension to include docstringsNumPy docstrings Docstrings style

Type annotationsSpecify types

Python domain Roles and directives

24 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

Table 28: Select exemplary referencesReference TopicSample automodule Autodoc demo with RTD Sphinx themeExample NumPy Strings Example docstringsType annotations RealPython guideInfo field lists Resultant reST syntax

extlinks

The extlinks extension functions like xref , but is exceptionally efficient for common websites. Usage is described atextlinks procedures

Not included with Sphinx

• xref

• BibTeX

xref

Michael Jones’ xref extension helps manage links to arbitrary URLs that can not be accessed via Intersphinx. A simplerole is used to insert links, and usage is described at xref procedures

xref is configured with Sphinx via its placement in the exts directory and it can integrate with Read the Docs

BibTeX

BibTeX is a special type of syntax that AAAAAA use to make citations for books. The BibTeX Sphinx extensionconverts refs.bib into formatted book citations

If know the ISBN for a particular book, you can usually get the BibTeX from OttoBib

Table 29: Select references within AAAAAAReference TopicBibTeX procedures Usagerefs.bib File structureBooks Citation catalogue

4.3. Concepts 25

AAAAAA Documentation, Release 0.4.0

Table 30: Select referencesReference TopicBook Information sourceBibTeX Citation formatBibTeX Sphinx extension Converts BibTeXOttoBib Contains BibTeX for booksISBN Unique identifier for booksBibTeX Entry and Field Types Syntax specificationsConvention for citing multiple authors Use of et. al

sphinx-autobuild

sphinx-autobuild is a package that automates the iterative process of manual builds. This is particularly useful whenproofreading documentation

Table 31: Select references within AAAAAAReference TopicSphinx Documentation engineBuilding manually UsageBuilding automatically Usage

Table 32: Select referenceReference Topicsphinx-autobuild User manual

Analysis

• Jupyter

• Numerical conda packages

Jupyter

Jupyter Notebooks enable an interactive development style for creating algorithms, and for quickly rendering equationsin LaTeX. The interactive style of Jupyter Notebooks make it easy to use numerical conda packages. The UnofficialJupyter Notebook Extensions provide additional functionality

Table 33: Select references within AAAAAAReference TopicAAAAAA Jupyter Notebook viewer View all Jupyter NotebooksDeveloper enviroment SetupNotebooks structure File structure

26 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

Table 34: Select referencesReference TopicCorey Schafer Jupyter Notebook tutorial Recommended YouTube tutorialMarkdown Syntax for making links, tables, etc.Tables generator for assorted languages Syntax generator

Table 35: Select extensionsExtension FunctionCollapsible Headings Section managementTable of Contents (2) Automatic section linkingVariable Inspector Data value inspectionLive Markdown Preview Quick previewing for LaTeX and tables

Tip: The Jupyter Notebook viewer for AAAAAA can render any Jupyter Notebook from the AAAAAA repositoryinside of a web browser, even if you don’t have Jupyter

Numerical conda packages

Table 36: Numerical analysis packagesPackage info Official tutorial (s) YouTube tutorialNumPy Quickstart tutorial NumPyMatplotlib Tutorials Matplotlibpandas 10 Minutes to pandas pandas

Testing

pytest

AAAAAA use pytest, a conda package, to verify that source code is functioning as expected

VS Code natively integrates with pytest, and additional functionality is provided by the VS Code Python Test Explorerextension

Table 37: Select references within AAAAAAReference TopicDeveloper environment SetupCode structure Specific componentsTesting WalkthroughVS Code Integrationpytest procedures Usage

4.3. Concepts 27

AAAAAA Documentation, Release 0.4.0

Table 38: Select referencesReference Topicpytest Official documentationcodebasics pytest tutorial Recommended YouTube tutorialpytest tutorials Official tutorials

Distributing

PyPI

Coming soon

4.3.2 Project structure

Access

Source code and documentation for AAAAAA are located at the AAAAAA repository, which is hosted by GitHub

Contents

Some select demonstrative contents of the AAAAAA repository:

AAAAAA/src/

AAAAAA/__init__.pyledger.py

test/test_ledger.pytest_utilities.py

doc/index.rstconf.pymake.bat

nbs/src/

ledger.ipynbdoc/

version-stats.ipynb.vscode/

settings.json.gitignorea6.ymlsetup.pyREADME.mdTODO.md

28 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

Table 39: Project contentsName FunctionAAAAAA/ Project root directorysrc/ Python source codetest/ pytest test codedoc/ Sphinx-style documentationnbs/ Jupyter notebooks.vscode/ VS Code settings.gitignore Git configurationa6.yml a6 conda environmentsetup.py pytest configurationREADME.md Has URL for documentation websiteTODO.md Task planning

4.3.3 Documentation

Contents

• Sphinx

– Structure

– Style

* Specific syntax

* Common Conceptual Capitalizations (C3)

* Whitespace and line breaking

– Simple example

• Jupyter Notebooks

Table 40: Select referencesReference TopicPython Developer’s Guide Official Python guide to documentingRealPython guide to documenting Python General documentation practices for Python

Sphinx

Note: The Tools: Sphinx section explains how Sphinx works, but this is an elaboration of specific documentationcomponents in AAAAAA

Structure

4.3. Concepts 29

AAAAAA Documentation, Release 0.4.0

AAAAAA/doc/

conf.pyrequirements.txtexts/

xref.pyMakefilemake.batindex.rstgetting-started/

quickstart.rstexamples.rstwhat-next.rst

user-guide/index.rsttransactions.rst...

dev-guide/index.rstenvironment/

index.rstdocumenting.rst...

concepts/index.rsttools.rst...

indices/index.rstreferences/

...refs.bibbooks.rst

Name Functionconf.py Sphinx configurationrequirements.txt Read the Docs configurationexts/xref.py xref Sphinx extensionMakefile , make.bat Building documentation, from sphinx-quickstartdoc/index.rst Homepage of documentation for AAAAAAgetting-started/ , user-guide/, etc. Directories for documentation sectionsquickstart.rst , what-next.rst , etc. reStructuredText filesrefs.bib Citations for books (in BibTeX format)

Style

• Specific syntax

• Common Conceptual Capitalizations (C3)

• Whitespace and line breaking

AAAAAA adopt stylistic recommendations from common sources, with some particular emphases

30 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

Table 41: Select references within AAAAAAReference TopicreStructuredText Conceptual explanationNapoleon Conceptual explanationNapoleon example Usage

Table 42: Select referencesReference TopicPython Developer’s Guide General reST style guideDoc8 reST linter Linter for reST1

Tip: The .rst files in AAAAAA should clearly portray stylistic components. Look around in them for more examplesafter reviewing the below considerations

Specific syntax

1. Nothing should be prefixed with :std: because components of the standard domain do not require it

2. Use labels (:ref:) to reference content within AAAAAA rather than specific .rst (:doc:) references, in casetoctrees change

3. Labels should be lowercase-hyphenated, and should use similar categorical naming when possible:

• tools-anaconda

• git-view-project-log

Tip: You can inspect all labels in AAAAAA via the updating labels procedure

4. There should be regular text between two different links so that the links can be clearly differentiated:

Yes NO!!!Extensions for Sphinx Sphinx extensions

Common Conceptual Capitalizations (C3)

1. Link capitalization should be natural with regard to the rest of the sentence, unless the thing you are describinghas special capitalization

• Links are here, but here are links

• The NumPy package thinks it is special

• pytest does too

1 Automatically runs via the reStructuredText extension for VS Code

4.3. Concepts 31

AAAAAA Documentation, Release 0.4.0

Table 43: Common Conceptual Capitalizations (C3)Beginning of sentence ElsewhereAnaconda AnacondaCommand Palette Command PaletteConda condaDocstrings docstringsGit GitInternet InternetIntegrated terminal integrated terminalIntersphinx IntersphinxMarkdown MarkdownMiniconda MinicondaNapoleon napoleonNumPy NumPyOpen-source open-sourcepytest pytestPython Python

Whitespace and line breaking

Many of these are exemplified below in the documentation example

1. Use a blank line at the end of .rst files

2. Indent 3 spaces (especially for nested lists)

3. Indent a single space after #. or after *

Note: If using a directive underneath #. or *, make sure its .. aligns with the text that is singly-spaced after#. or *

4. Use 2 lines of whitespace above any overlined section headings

5. Lines should be a maximum length of 79 characters, unless you are using a code-block that itself conformsto PEP 8 or an appropriate standard. If you are using a role and you need to line break:

1. Place the role on its own line:

Use 2 :wiki-pg:`lines <Line_(text_file)>` of:wiki-pg:`whitespace <Whitespace_character>` above any:doc:`overlined section headings <sphinx:usage/restructuredtext/basics>`

2. If the line is still too long, then line break between the title and the target, with the < at the beginning of anew line:

.. [#] Recommeded in:yt-vid:`Carol Willing's Practical Sphinx talk from PyCon 2018<0ROZRNZkPS8>`

3. If the line is still too long, then use a \ to escape a new line inside the target and/or title:

:stack-q:`https://stackoverflow.com/questions/1441010/the-shortest-possible\-output-from-git-log-containing-author-and-date

(continues on next page)

32 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

(continued from previous page)

<1441010/the-shortest-possible-output-from-git-log-containing-author-and-\date>`:

• Note that this works, but there may not be syntax highlighting in the above code-block because ofthe \-escapes for new lines

6. Use a blank line before directive content, but not before directive options:

.. csv-table:: Select references:align: center:header: Reference, Topic

:xref:`Python.org <Python>`, Official information:doc:`python:tutorial/index`, Official tutorial

7. If a directive option requires a line break, make sure to indent the following line if it starts with a role:

.. literalinclude:: sample-doc.rst:language: rest:caption: What the :ref:`reST <tools-restructured-text>` for

:ref:`sample-doc.rst <sample-doc>` looks like:

• Otherwise, simply line break without indenting

• Note that this does not apply to directive arguments:

.. csv-table:: :ref:`conda:concept-conda-package` required for:term:`AAAAAA`:align: center

8. See the a6 packages table for some sample csv-table syntax with appropriate line breaks

• You should only need " in csv-tables for line breaks that are necessary when , is also needed

• For consistency, :align: should come before :header:

.. csv-table:: :ref:`conda:concept-conda-package` required for:term:`AAAAAA`:align: center:header: :ref:`Package <conda:concept-conda-package>`, Function, "

:ref:`Setup Phase <dev-env-intro>`", ":ref:`Channel <conda:channels-glossary>`"

9. Use a single space before footnotes

Simple example

Though it is an orphan page, check out the HTML form of sample-doc.rst!

Listing 1: What the reST for sample-doc.rst looks like

:orphan:

.. _sample-doc:

(continues on next page)

4.3. Concepts 33

AAAAAA Documentation, Release 0.4.0

(continued from previous page)

##########Page title##########

Welcome to this :wiki-pg:`file <Computer_file>`! Don't forget the two:wiki-pg:`blank lines <Line_(text_file)>` above the:doc:`overlined section heading <sphinx:usage/restructuredtext/basics>`!

You ready for a :doc:`list <sphinx:usage/restructuredtext/basics>`?

#. Item 1 (one :wiki-pg:`space <Whitespace_character>` after ``#.``)#. Item 2 (no :wiki-pg:`vertical whitespace <Newline>` above)

* Item 3 (needs :wiki-pg:`vertical whitespace <Newline>` above)

* Item 4 (one :wiki-pg:`space <Whitespace_character>` after ``*``)

* Item 5 (:wiki-pg:`indented <Indentation_(typesetting)>` 3:wiki-pg:`spaces <Whitespace_character>`)

*************Chapter title*************

Welcome to this:doc:`chapter <sphinx:usage/restructuredtext/basics>`! Don't forget the two:wiki-pg:`blank lines <Line_(text_file)>` above the:doc:`overlined section heading <sphinx:usage/restructuredtext/basics>`! [#]_

.. csv-table:: Reference, Topic example (NOT ``"Reference", "Topic"``):align: center:header: Reference, Topic

:ref:`concepts-doc-example`, "A:wiki-pg:`render <Rendering_(computer_graphics)>` of the:ref:`reST <tools-restructured-text>` for this :wiki-pg:`webpage <Webpage>`":term:`OHIO`, :wiki-pg:`Development <Software_development>` philosophy [#]_

Section title=============

Welcome to this :doc:`section <sphinx:usage/restructuredtext/basics>`! Only one:wiki-pg:`blank line <Line_(text_file)>` needed above the:doc:`section heading <sphinx:usage/restructuredtext/basics>`! Let's discuss:ref:`documentation <concepts-doc>` (NOT ``:std:ref:`documentation<concepts-doc>``) for :term:`AAAAAA`, which is a specific type of:wiki-pg:`software documentation <Software_documentation>`

.. admonition:: How about this custom :xref:`admonition <admonition>`?

Check out this :wiki-pg:`blank line <Line_(text_file)>` ^^

#. Item 1#. Item 2

.. note::

(continues on next page)

34 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

(continued from previous page)

Check out the :wiki-pg:`indentation <Indentation_(typesetting)>` for this:doc:`directive <sphinx:usage/restructuredtext/directives>`, after a:doc:`list <sphinx:usage/restructuredtext/basics>`

* Item 3

.. tip::

Because there is a ``*`` above, there is one less:wiki-pg:`space <Whitespace_character>` of:wiki-pg:`indentation <Indentation_(typesetting)>` for this:doc:`directive <sphinx:usage/restructuredtext/directives>`

Subsection title----------------

Welcome to this :doc:`subsection <sphinx:usage/restructuredtext/basics>`! Onlyone :wiki-pg:`blank line <Line_(text_file)>` needed above the:doc:`section heading <sphinx:usage/restructuredtext/basics>`!

.. rubric:: Footnotes

.. [#] A :doc:`footnote <sphinx:usage/restructuredtext/basics>` from above.Notice how the :wiki-pg:`indentation <Indentation_(typesetting)>` startsafter the :wiki-pg:`line break <Newline>`?

.. [#] Oh, so that's how you do multiple:doc:`footnotes <sphinx:usage/restructuredtext/basics>`. Check out the:wiki-pg:`blank line <Newline>` below

Jupyter Notebooks

Note: The Tools: Jupyter section explains how Jupyter works, but this is an elaboration of specific components inAAAAAA

AAAAAA/nbs/

dev/ledger.ipynb

src/ledger.ipynbutilities.ipynb

doc/version-stats.ipynbversion-stats.csv

Name Functiondev/ Created during developmentsrc/ Complements source codedoc/ For measuring version statisticsledger.ipynb, version-stats.ipynb, etc. Jupyter Notebooksversion-stats.csv csv-table integration for version statistics

4.3. Concepts 35

AAAAAA Documentation, Release 0.4.0

Tip: The Jupyter Notebook viewer for AAAAAA opens at the nbs/ directory and can render any Jupyter Notebookfrom the AAAAAA repository inside of a web browser, even if you don’t have Jupyter

4.3.4 Code

Note: The Tools section explains general Python and pytest concepts, the user guide is a walkthrough of softwarefeatures in AAAAAA, and the testing section is a walkthrough of pytest code, but this is an elaboration of specificcomponents in AAAAAA from a developer’s perspective

• Structure

• Style

• Elaborately Embellished Explanatory Enhancements (E4)

Structure

Table 44: Select references within AAAAAAReference TopicPython Conceptual explanationpytest Conceptual explanationUser guide WalkthroughTesting Walkthrough

Table 45: Select referencesReference TopicPackages Directory structuringGood Integration Practices Integrating test code

In accordance with pytest configuration specifications, AAAAAA are structured as follows:

AAAAAA/src/

AAAAAA/__init__.pyledger.py

test/test_ledger.pytest_utilities.py

setup.py

Name Functionsrc/AAAAAA/ Python source codetest/ pytest test codesetup.py pytest configuration

36 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

Style

Table 46: Select referencesReference Topic

PEP 8Official Python style guide

PEP 257Docstring conventions

1. Items of particular emphasis:

• Lines should be a maximum length of 79 characters, except comments and docstrings, which should be amaximum of 72 characters

– The VS Code ruler settings help with this

• Two spaces should precede a comment

2. Per a recommended Python quote convention:

symbol_like = 'begin_index' # Symbol-like termnatural = "Documentation optimality" # Natural language message

Elaborately Embellished Explanatory Enhancements (E4)

Table 47: Select references within AAAAAAReference TopicNapoleon Conceptual explanationNapoleon procedures Usage

Table 48: Select referencesReference Topic

PEP 257Docstring conventions

PEP 484Syntax to indicate types

NumPy docstrings Docstring stylePython domain Syntax guide

Source code is enhanced with type annotations and docstrings containing Python domain components for reST , sothat napoleon can create pretty documentation elements that explain source code, like this info field list:

explanation(what, who, how, where, when, how_many)Explain something to somebody in a certain way at a certain place on a certain day, a certain number of timeytimes

Parameters

• what (object) – are you trying to explain?

• who (str) – even cares?

• how (str) – you gon’ do that?

• where (str) – are you ‘splaining it?

• when (datetime.date) – do we receive the coupons you promised?

4.3. Concepts 37

AAAAAA Documentation, Release 0.4.0

• how_many (int) – parcels of knowledge?

Returns with newfound knowledge

Return type object

Raises

• ValueError – if the explanation is not understood

• TypeError – if the explanation is in the wrong language

Attention: We interrupt your drooling to return to alnoki

Conveniently, documentation elements can be created with simple reST directives like:

.. autoclass:: AAAAAA.ledger.Transaction

After a documentation element has been created, it can be referenced using the Python domain:

Listing 2: Let’s talk about AAAAAA.ledger.Transaction

Let's talk about :py:class:`AAAAAA.ledger.Transaction`

Real Elaborately Embellished Explanatory Enhancements (E4), like the example below, also have a [source] featurethat links directly to source code, except when viewing documentation for AAAAAA in PDF format

Example

AAAAAA.ledger.Transaction (<- yes, that’s a link)

4.3.5 Configurations

AAAAAA/a6.yml.gitignore.vscode/

settings.jsondoc/

conf.pyrequirements.txtexts/

xref.pysetup.py

Contents

• Conda

– a6.yml

• Git

– config

38 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

– .gitignore

• Vim

• VS Code

– settings.json

* Workspace

* User

• Sphinx

– conf.py

* Extensions

* AAAAAA project info

* File handling

* Website

* Document generation

* Link management

• Read the Docs

– requirements.txt

• pytest

– setup.py

Conda

Table 49: Select reference within AAAAAAReference TopicAnaconda Conceptual explanation

a6.yml

a6.yml specifies a conda environment that you will need to do development for AAAAAA. See the conda proceduresfor more information on how to use it

name: a6channels:

- conda- conda-forge

dependencies:- python- conda- pep8- sphinx- sphinx_rtd_theme- doc8- sphinxcontrib-bibtex

(continues on next page)

4.3. Concepts 39

AAAAAA Documentation, Release 0.4.0

(continued from previous page)

- sphinx-autobuild- jupyter- jupyter_contrib_nbextensions- numpy- matplotlib- pandas- pip- pytest

Git

Table 50: Select reference within AAAAAAReference TopicGit Conceptual explanation

config

git-config helps store your identity the way that you want it to appear in the Git log, and allows you to use Vim. The Gitconfiguring procedures include precise instructions on how to get started with git-config, which you shouldn’t needthat often

.gitignore

.gitignore describes which files in the AAAAAA project tree do not need to be tracked by Git. It contains somecomments to help separate content into sections

Vim

Table 51: Select reference within AAAAAAReference topicVim Conceptual explanation

Vim text editor is helpful for creating commit messages from the VS Code integrated terminal, and it comes with syntaxhighlighting that helps you figure out if you are adhering to Git commit guidelines. This functionality is automaticallyenabled, except on a Mac, so the Git setup procedure includes instructions to create a .vimrc file with the appropriatecontents if you are using a Mac

Vim text editor is also recommended as an extension to VS Code, and it is configured in settings.json using the officialconfiguration options

VS Code

Table 52: Select reference within AAAAAAReference topicVS Code Conceptual explanation

40 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

settings.json

VS Code has both user and workspace settings. For the most part, you will only have to modify the AAAAAA workspacesettings except for when you are first setting up the development environment

Workspace

See the VS Code procedures for more information about how to view the AAAAAA workspace settings and an inter-pretation of a few specific options

The AAAAAA workspace settings are separated into categories with comments. For consistency, X11 color names areused

User

You may have to use the developer environment setup to get a few key user settings correct, but for the most part theyare not needed because they will be overrided by workspace settings if you are developing for AAAAAA

Note: The Vim extension can change a few user settings throughout usage if you use the vim.statusBarColorControl option, don’t worry about this

Sphinx

Table 53: Select references within AAAAAAReference topicSphinx Conceptual explanationDistributing documentation Walkthrough

Table 54: Select referencesReference topicsphinx-quickstart Official setup assistantQuickstart screencast Video walkthroughconf.py Sphinx settings options

conf.py

If you create a Sphinx project using sphinx-quickstart, you will end up with a conf.py file in your documentationroot directory. For AAAAAA, most of the default Sphinx configuration options from sphinx-quickstart are used, butthere are some additions and modifications. The conf.py in AAAAAA has also been shuffled around a bit so that it canbe logically explained here

Because conf.py is a .py (Python) file, it can be explained using the literalinclude directive and napoleon. Forthe most part, conf.py is a collection of global module variables. Starting from the beginning of the file:

4.3. Concepts 41

AAAAAA Documentation, Release 0.4.0

Contents

• Extensions

• AAAAAA project info

• File handling

• Website

• Document generation

• Link management

Extensions

Listing 3: Path setup

import osimport syssys.path.insert(0, os.path.abspath('exts')) # For xrefsys.path.insert(0, os.path.abspath('../src')) # For napoleonsys.path.insert(0, os.path.abspath('.')) # For conf.py in napoleon

Relative to the documentation root directory, this gives Sphinx access to the following paths:

Path Purposeexts Contains xref../src Where napoleon checks for source code. Allows napoleon to access conf.py

conf.extensionsWhich extensions to use

Includes extensions that are:

• Automatically installed via sphinx-quickstart

• Selected from the built-in Sphinx extensions for usage in AAAAAA

• Used for AAAAAA, but not included in the built-in Sphinx extensions

AAAAAA project info

conf.project = 'AAAAAA'What to call this Sphinx project

conf.copyright = '2019, alnoki'Basic copyright information

conf.author = 'alnoki'Who even made this?

conf.version = '0.4'Just MAJOR.MINOR for the version

42 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

conf.release = '0.4.0'MAJOR.MINOR.PATCH for the version

File handling

conf.master_doc = 'index'The top-level .rst file

For AAAAAA, is inside of the documentation root directory

conf.exclude_patternsWhat to ignore

When building documentation, don’t use files or paths with these patterns

conf.html_static_path = []Directory with supplementary data

Website

conf.html_theme = 'sphinx_rtd_theme'What the website should look like

For AAAAAA, use the Read the Docs Sphinx Theme

conf.html_theme_optionsRead the Docs theme options

These are only configured if they differ from the default options

conf.linkcheck_ignoreIgnore when checking links

These URLs are just for building documentation, so ignore them

Document generation

These were created during sphinx-quickstart, and have not been modified. See conf.py for the original comments thatwere automatically generated

Per the napoleon procedures, these have empty docstrings

conf.htmlhelp_basename

conf.latex_elements

conf.latex_documents

conf.man_pages

conf.texinfo_documents

conf.epub_title

conf.epub_exclude_files

4.3. Concepts 43

AAAAAA Documentation, Release 0.4.0

Link management

conf.intersphinx_mappingContains intersphinx base URLs

conf.extlinksContains extlinks base URLs

conf.xref_linksContains xref URLs

Read the Docs

Table 55: Select reference within AAAAAAReference TopicRead the Docs Conceptual explanation

requirements.txt

Some of the Sphinx extensions used in AAAAAA are not built-in, so the remote computer that performs the Read theDocs build process needs information on how to use them

Unlike the a6 conda environment which uses conda packages, the Read the Docs builder uses a requirements file thatindicates which PyPI packages to download

Because xref is not on the PyPI, it is simply included in the exts directory of the documentation root directory. OtherSphinx extensions that are not built-in, however, must be specified in requirements.txt:

Listing 4: requirements.txt

sphinxcontrib-bibtex

On your Read the Docs account, you will need to navigate to Projects → AAAAAA → Admin → Advanced Settingsand update Requirements file: with the path of requirements.txt for this to work

pytest

Table 56: Select reference within AAAAAAReference Topicpytest Conceptual explanation

setup.py

Per official pytest recommendations, the AAAAAA project directory contains a setup.py file outside of both source andtest code directories, with the minimum available content:

44 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

Listing 5: AAAAAA/setup.py

from setuptools import setup, find_packages

setup(name='AAAAAA', packages=find_packages())

This enables pytest discovery

4.3.6 Zen

Alnoki’s Inspired Philosophies, Adopted and Implemented in Practice (AIP)2

1. Silly acronyms actually make it easy to remember things

2. Test and document from the beginning to prevent massive runtime debug headaches

3. Have DRY (don’t repeat yourself)1 code: decompose as much as possible

4. Documentation should enable another to re-create source and test code2

5. Have STUPID simple tests.3 Don’t recursively “test the test code”

6. Documenting and testing adds perspective beyond the development of source code alone

7. Consider DO-178B as a model for software design assurance4

8. Legacy conventions shant prevent the adoption of a new worthwhile philosopy

9. Play around and “whiteboard” software during initial development5

10. Read documentation out loud6

11. Py like you reST , reST like you Py7

12. “We, the coders, are foreigners, seeking citizenship in the computer’s locale”8, so respect the house rules

13. Your legacy is the documentation

14. Make content for yourself because you like it9

15. Quality trumps quantity when you are creating content, so just keep creating

The spirit of alnoki’s apps

1. Open-source, d00d

2. Tools should be free, otherwise, make them yourself10

3. When in doubt, link (or you might forget later)

1 Acronym from Corey Schafer2 From Software Requirements Documents (SWRDs) and Software Design Documents (SDDs) standards at Garmin3 From a tip that embedded systems code should be “stupid simple”, given by Daniel Santos, co-founder of 219 Design4 AHRS products from Garmin are DO-178B Level A5 From a comment by Brett Glasner, that whiteboarding is the most fun part of software design6 Recommeded in Carol Willing’s Practical Sphinx talk from PyCon 20187 Adapted from advice given by Tom C. Bryan of the NASA Marshall Space Flight Center Flight Robotics Laboratory (fly like you test, test

like you fly) that flight testing and flight operations should be identical - to indicate that software development in practice should match proceduraldocumentation

8 From _why’s (Poignant) Guide to Ruby, Chapter 39 From a Corey Schafer interview: I believe the most important lesson I’ve learned is that you should make content for yourself

10 Taken from various elements in a Linus Torvalds interview

4.3. Concepts 45

AAAAAA Documentation, Release 0.4.0

4. If you are proofreading, enjoy the content and go slow11

5. Like in life, there are a lot of things to do, so OHIO

6. PEP 8 provides a repeatable and official means for formatting. Use it!!!

7. Write functional programs, which should be easy to understand and test

8. Add content to versions incrementally, like you are making a Minimum Viable Prototype (MVP)

9. Add an index.rst in documentation directories so you can find what you are looking for

Further reading

Need some more inspiration? Try:

import this

4.4 Distributing

4.4.1 Documentation

Table 57: Select references within AAAAAAReference TopicRead the Docs Conceptual explanationSphinx Conceptual explanationSphinx configurations OptionsRTD configurations OptionsVersioning Checklist

Table 58: Select referencesReference TopicQuickstart tutorial Start a Read the Docs with Sphinx projectRead the Docs build process Generation process

Documentation for AAAAAA was initially created using the Read the Docs with Sphinx getting started guide, whichshould have you on your way if you want to create a similar website

Contents

• Creating a project

• Monitoring builds

• Managing versions

• Creating a PDF

11 Mantra of Caye Caulker

46 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

Creating a project

If you complete sphinx-quickstart, you’ll have a Sphinx project on your computer, but you’ll need to set up GitHubintegration before your documentation shows up on the Internet

If you decide to use any Sphinx extensions, you’ll need to indicate them in conf.py, and potentially in requirements.txtif they are not built-in extensions

Monitoring builds

The Sphinx procedures describe how to build documentation on your computer, which you’ll want to do as you write.This process uses the make files generated by sphinx-quickstart

Read the Docs will create a new website of your documentation whenever you commit. On your Read the Docsaccount, it is important to become familiar with the builds monitoring interface at Projects → AAAAAA → Builds.You should check this when you are releasing a new version at the very least, and definitely whenever you use a newSphinx extension

If you experience a failed build, you probably just need to update conf.py or requirements.txt

Managing versions

As you create development branches, you’ll start to upload new sets of documentation with every commit, and you’llwant to enable different versions. On your Read the Docs account, you will need to navigate to Projects → AAAAAA→ Versions to enable the rendering of different tags and branches

It is helpful to enable whatever development branch you are working on so that you can see how it will actually appearin your browser, and as long as you use the suggested versioning procedures, only the last tagged version on the masterbranch will appear to others as the official website (unless they manually choose a different version)

When you merge, it makes sense to disable the development branch you were just working on, then tag the new versionon the master branch and enable it instead, so that your website will officially show the latest version

You can use version-stats.ipynb, which is a Jupyter Notebook, to track progress as you go. Using a csv-table, youcan integrate the results as reStructuredText in the version statistics section. See the versioning procedures for morechecklist-like instructions on managing all of this

Creating a PDF

Read the Docs will automatically create a PDF of your documentation that you can access from your Read the Docsaccount at Projects → AAAAAA → Downloads. The structural layout is dictated by the toctrees in your project and bythe headings in conf.master_doc

The website is considered the primary way to view documentation for AAAAAA, but the PDF is useful for measuringthe amount of content generated for a version release. You can also follow the procedures to build a PDF on yourcomputer if you are okay with downloading a particularly large LaTeX library

Content is, of course, rendered differently in the PDF and in the website, especially for:

• guilabels like this

• BibTeX

• Elaborately Embellished Explanatory Enhancements (E4)

• URLs in a directive argument for a csv-table

• The automatic indices

4.4. Distributing 47

AAAAAA Documentation, Release 0.4.0

4.5 Testing

Coming soon

4.6 Procedures

Here are some checklist-like instructions for common development tasks, which assume at least a rough understandingof concepts from the developer guide

These should either be followed exactly, or updated

Tip: Py like you reST , reST like you Py1

4.6.1 Conda

Table 59: Select referencesReference TopicAnaconda AAAAAA conceptual explanationManaging environments Official practical reference

Attention: Most of these instructions assume you have already done the developer environment setup, which willhelp you integrate conda with VS Code

Contents

• Tidying up

• Creating a6 from scratch

• Importing a6

• Installing AAAAAA for testing

• Using a new package

Tidying up

1. Start up conda

2. Activate the a6 environment

3. Use conda update to get the latest packages:

conda update --all

1 From Alnoki’s Inspired Philosophies, Adopted and Implemented in Practice (AIP)2

48 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

Tip: This will usually get as many packages as possible from the official conda channel

4. Use conda clean to get rid of excess files:

conda clean --all

5. Use conda list to inspect the new conda environment:

conda list

Creating a6 from scratch

1. Use the packages table to indentify which packages you need

2. Start up conda, then use conda create to make a new conda environment with packages from the conda channel:

conda create -n a6 python conda pep8 sphinx sphinx_rtd_theme jupyter numpy→˓matplotlib pandas pip pytest

Note: Be sure to copy and paste the whole box! It may scroll to the right

3. Activate the a6 environment

4. Install the remaining packages from the conda-forge:

conda install -c conda-forge doc8 sphinxcontrib-bibtex sphinx-autobuild jupyter_→˓contrib_nbextensions

Note: Be sure to copy and paste the whole box! It may scroll to the right

5. Install AAAAAA for testing

6. Tidy up

Importing a6

1. Start up conda from inside the AAAAAA project directory, then import the necessary conda packages:

conda env create -f a6.yml

2. Activate the a6 environment

3. Install AAAAAA for testing

4. Tidy up

Installing AAAAAA for testing

Per pytest integration practices:

1. From inside the AAAAAA project directory, use a6 from inside the VS Code integrated terminal:

4.6. Procedures 49

AAAAAA Documentation, Release 0.4.0

pip install -e .

2. Tidy up

Using a new package

1. Add the package to

1. The packages table

2. a6.yml

3. The instructions for creating a6 from scratch

• Here, use the same order for the separate channels as from top to bottom in the packages table

4. An step somewhere in the developer environment setup

2. Activate the a6 environment

3. Install the desired package

4. Tidy up

4.6.2 Git

Table 60: Select reference within AAAAAAReference TopicGit Conceptual explanation

Table 61: Select referencesReference TopicGit manual Quick practical referenceGit book In-depth conceptual explanationsGit commit guidelines Official message guidelinesGit commit message style Tell the codebase what to do

Contents

• Configuring

– Setting up

– Updating user credentials

• Inspecting history

– Viewing the project log

– Listing project committers

– Get commit statistics

• Development tasks

– Committing

50 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

* Quick fixes

– Tagging

– Branching

– Merging

• Changing commit credential history

Configuring

• Setting up

• Updating user credentials

Table 62: Learning VimReference TopicInteractive Vim tutorial Learn minimum necessary VimVim cheatsheet Common commandsVim configuration Configuration for AAAAAA

Setting up

Use the VS Code integrated terminal for first-time Git setup:

1. Configure your identity:

git config --global user.name alnokigit config --global user.email 43892045+alnoki@users.noreply.github.com

2. Indicate Vim as the default editor and use it to verify your identity:

git config --global core.editor Vimgit config --global -e

3. At this point, you will be in Vim. If you your identity looks right, you can exit without saving by typing :q!then return

4. Vim comes with syntax highlighting for commit messages, but if you are using a Mac you may have to enable it,by creating a .vimrc file at ~/.vimrc with the following:

filetype plugin indent onsyntax on

Updating user credentials

Per git-config:

1. Use the VS Code integrated terminal to edit git-config using Vim:

4.6. Procedures 51

AAAAAA Documentation, Release 0.4.0

git config --global -e

2. Type i then return to get into insert mode, then make your changes:

[user]name = alnokiemail = 43892045+alnoki@users.noreply.github.com

[core]editor = Vim

3. Type Esc, then :x, then return, to save and close

4. To check that the user credentials have updated:

git config --global --list

Inspecting history

• Viewing the project log

• Listing project committers

• Get commit statistics

Table 63: Core less commandsKey Functionreturn scrollq exith help

Viewing the project log

Per git-log:

1. In the VS Code integrated terminal:

git log

2. This will open the less pager

3. A condensed version:

git log --oneline

• Also (This might only work on a Mac):

git lg

52 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

Listing project committers

Table 64: Select referencesReference Topicgit-log Syntax referenceListing Git project developers Sorting unique instancesGit log formatting options Practical syntax examples

1. In the VS Code integrated terminal, isolate all unique instances of a field:

git log --pretty="Author name: %an" | sort | uniqgit log --pretty="Author email: %ae" | sort | uniqgit log --pretty="Committer name: %cn" | sort | uniqgit log --pretty="Committer email: %ce" | sort | uniq

2. Inspect all of these fields at once, for the entire project history:

git log --pretty="%an, %ae, %cn, %ce"

Get commit statistics

Table 65: Select referencesReference Topicgit-show Time inspectiongit-rev-list Commit number inspectionDenCode Convert time standards

Typically you will do this once a tag has already been made

1. In the VS Code integrated terminal, use git-show to extract the IS0 8601-formatted time:

git show -s --format=%cI 0.4.0

2. On DenCode, convert using UTC and ISO8601 Date (Extend)

3. To see the number of commits:

git rev-list --count 0.4.0

Development tasks

• Committing

– Quick fixes

• Tagging

• Branching

• Merging

4.6. Procedures 53

AAAAAA Documentation, Release 0.4.0

Committing

Table 66: Select referencesReference Topicgit-add Prepare changesgit-commit Create snapshot of project changesgit-push Upload changes to GitHubGit commit guidelines Official message guidelines

1. Verify the state of the project using the VS Code integrated terminal:

git pullgit log

2. Save and close any open files

3. Update your Git credentials and verify as needed

4. Use the VS Code symbol input to type:

• view source control

5. Use the Source Control interface to stage changes

• Consider using the Command Palette to select

– Git: Stage All Changes

• Or, equivalently:

git add -A

6. In the integrated terminal:

git commit

Note: This will open Vim

7. Compose a message that tells the codebase what to do

8. Use the integrated terminal to verify the commit looks alright and that the commit identities are okay

git log

9. If you want complete redundancy, recall the listing committers procedure:

git log --pretty="%an, %ae, %cn, %ce"

10. Use the integrated terminal to push and verify

git pushgit log

11. Optionally verify results at the AAAAAA repository

54 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

Quick fixes

Table 67: Select referencesReference Topicgit-reset Fix mistakesVim 325 error If you commit incorrectly

1. If you made a mistake in your commit but you haven’t pushed yet, you can try again via git-reset:

git reset --soft HEAD^

2. If you are experiencing a Vim 325 error, you may need to delete (if it exists) AAAAAA/.git/COMMIT_MSG.swp

Tagging

Table 68: Select referencesReference Topicgit-tag Assign a unique identifier to a commitMessage style Tell the codebase what to dogit-push Upload changes to GitHubGit commit guidelines Long message guidelines

1. View the project log to verify the commit in question

2. Use the VS Code integrated terminal to view existing tags

git tag

3. Create an annotated tag:

git tag -a 0.3.0

Note: This will open Vim

4. Compose a message that tells the codebase what to do and includes a lengthier description if appropriate

5. Verify by viewing the project log

6. Push with tag following:

git push --follow-tags

7. Verify results at the AAAAAA repository

Branching

Table 69: Select referencesReference Topicgit-branch Manage independent commit sequencesgit-checkout Switch branches

4.6. Procedures 55

AAAAAA Documentation, Release 0.4.0

1. View the project log to verify the commit in question

2. Inspect all branches using the VS Code integrated terminal:

git branch -a

3. Create and check out a new tracked branch:

git checkout -b dev/0.4.0

4. Verify:

git branch

5. The first time you commit a new branch to the AAAAAA repository, make sure to set upstream tracking:

git push -u origin dev/0.4.0

6. To check out a branch from the AAAAAA repository for the first time:

git checkout --track origin/dev/0.4.0

Merging

Table 70: Select referencesReference Topicgit-branch Manage independent commit sequencesgit-checkout Switch branchesgit-merge Combine branches

1. Use the VS Code integrated terminal to view available branches:

git branch

2. Checkout the appropriate branch:

git checkout master

3. Merge the desired branch

git merge dev/0.4.0

4. Verify the project log

Changing commit credential history

Table 71: Select referencesReference TopicChange author history GitHub instructionsGit filter-branch options Advanced syntax

If you are learning Git and you forget to either set up your identity and/or update your credentials when using differentcomputers, your committer list can end up looking like total nonsense. This is how you fix it

56 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

You should only need to do this once, after which you will have (hopefully) learned your lesson

Warning: This can totally mess stuff up if you are not careful

1. For the most part, follow GitHub.com instructions to change author history

• Before you push the corrected history, check out the unique project committers

2. If you forget to update your user credentials before committing and pushing (a whole bunch of times), use:

#!/bin/sh

git filter-branch --env-filter 'CORRECT_NAME="alnoki"CORRECT_EMAIL="43892045+alnoki@users.noreply.github.com"if [ "$GIT_AUTHOR_EMAIL" != "$CORRECT_EMAIL" ]then

export GIT_AUTHOR_NAME="$CORRECT_NAME"export GIT_AUTHOR_EMAIL="$CORRECT_EMAIL"export GIT_COMMITTER_NAME="$CORRECT_NAME"export GIT_COMMITTER_EMAIL="$CORRECT_EMAIL"

fi' --tag-name-filter cat -- --branches --tags

• This example will update all project commit credentials that do not have 43892045+alnoki@users.noreply.github.com as the author email

3. If you want to get more specific about your selections, play around with some more options:

#!/bin/sh

git filter-branch --env-filter 'OLD_NAME="Some d00d"OLD_NAME2="ikonla"OLD_EMAIL="not_alnoki@interweb.com"OLD_EMAIL2="d00000000d@l33t.com"CORRECT_NAME="alnoki"CORRECT_EMAIL="43892045+alnoki@users.noreply.github.com"if [ "$GIT_AUTHOR_NAME" = "$OLD_NAME" ] ||

[ "$GIT_AUTHOR_NAME" = "$OLD_NAME2" ]then

export GIT_AUTHOR_NAME="$CORRECT_NAME"export GIT_AUTHOR_EMAIL="$CORRECT_EMAIL"

fiif [ "$GIT_COMMITTER_EMAIL" = "$OLD_EMAIL" ] ||

[ "$GIT_COMMITTER_EMAIL" = "$OLD_EMAIL2" ]then

export GIT_COMMITTER_NAME="$CORRECT_NAME"export GIT_COMMITTER_EMAIL="$CORRECT_EMAIL"

fi' --tag-name-filter cat -- --branches --tags

4.6. Procedures 57

AAAAAA Documentation, Release 0.4.0

4.6.3 VS Code

Table 72: Select reference within AAAAAAReference TopicVS Code Conceptual explanation

Contents

• Managing settings

• Maximizing screen estate

• Improving efficiency

• Configuring rulers and tabs

• Changing colors

– Basic interface components

– Specific syntax components

Managing settings

1. Use the Command Palette to compare settings.json against defaults:

• Preferences: Open Raw Default Settings

Maximizing screen estate

You may need to modify settings for some of these to have an effect

1. For half-screen, use the VS Code Command Palette to experiment with the following commands:

• View: Toggle Tab Visibility

• View: Toggle Maximized Panel

• View: Toggle Panel

• View: Toggle Activity Bar Visibility

• View: Toggle Side Bar Visibility

• View: Toggle Status Bar Visibility

• View: Toggle Centered Layout

• View: Join All Editor Groups

• View: New Editor Group to the Right

• View: New Editor Group Below

• View: Zoom In (or Out)

• Workspaces: Duplicate Workspace in New Window

• Editor Font Zoom In (or Out)

2. For full-screen:

58 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

• View: Toggle Zen Mode

Improving efficiency

1. Use the VS Code Command Palette to experiment with the following commands:

• Focus Next Terminal

• View: Keep Editor (from closing)

• Bookmarks: Toggle

• Bookmarks: Jump to Next

• Bookmarks: Jump to Previous

• Search: Replace in Files

• Toggle Tab Key Moves Focus

Configuring rulers and tabs

1. Determine the relevant line break rule for your code style or documentation style

2. While viewing the filetype in question, use the Command Palette for inspection

• Change Language Mode

3. With 'x' corresponding to the filetype in question, select

• Configure ‘x’ language based settings. . .

4. Update settings.json in accordance with examples therein

Changing colors

• Basic interface components

• Specific syntax components

Basic interface components

1. Review the token color customization for the setting you want to modify

2. Choose an X11 color and add it to settings.json like the rest of the examples therein

Specific syntax components

1. Use the Command Palette to open the TextMate inspector

• Developer: Inspect TM Scopes

2. Click on whatever string you are interested in

3. Update the resultant textMateRules in settings.json with your desired X11 color

4.6. Procedures 59

AAAAAA Documentation, Release 0.4.0

4.6.4 Sphinx

Table 73: Select reference within AAAAAAReference TopicSphinx Conceptual explanation

Table 74: Select referencesReference TopicPractical Sphinx presentation Common usageProject setup screencast Start a projectSphinx quickstart tutorial Official tutorial

Contents

• Building documentation

– Manually

– Automatically

– PDF version

• Managing references

– Using Intersphinx

– Referencing external links

* xref

* extlinks

– Checking links

– Updating labels

– Referencing books

Building documentation

Builders enable you to create both website and PDF documentation styles. Make sure you are using a6 for the belowprocedures

Contents

• Manually

• Automatically

• PDF version

Manually

Per Carol Willing’s Practical Sphinx talk from PyCon 2018:

60 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

1. Activate the a6 environment from inside the documentation root directory if it is not already active

2. From the VS Code integrated terminal, build the HTML for documentation then start a server

make htmlpython -m http.server

3. Open http://localhost:8000/_build/html/index.html in a web browser to view the website for documentation

4. You can update the .rst files and repeat the process, but don’t start another server (unless you want an HTTPsocket error):

make html

5. Refresh the browser to see changes

6. Before committing, clear out the build:

make clean

Tip: You can automate this process if you want quick updates, like if you are proofreading documentation

Automatically

Table 75: Select reference within AAAAAAReference Topicsphinx-autobuild Conceptual explanation

Table 76: Select referenceReference Topicsphinx-autobuild Official user manual

1. Like in the manual build procedure, use the a6 environment from inside the documentation root directory viathe VS Code integrated terminal:

sphinx-autobuild . _build/html -B -s 1

sphinx-autobuild options:

-B Automatically open browser

-s Delay1 before opening browser

• This should automatically open a web browser

• The server should be at http://127.0.0.1:8000

2. Use control-c to stop the server

3. Keep in mind:

• Once the server is running, saved changes to any .rst files should cause your web browser to update what-ever part of the website you are viewing

1 If you try to use no delay at all, -s 0, the browser might not open

4.6. Procedures 61

AAAAAA Documentation, Release 0.4.0

• You will still need to manually navigate to the webpage you want to view

• If your web browser is set to a URL that ends with .html, the webpage will refresh in the samevertical position, but you may not be granted this luxury if the URL ends with something like .html#a-heading-you-clicked-on

• For some reason, at least on a Mac, you may need to quit your web browser, stop sphinx-autobuild viacontrol-c and then re-do the above before the auto-refresh behavior will work

PDF version

Note: Read the Docs will do this for you, but if you are so inclined it is possible to do it on your computer

1. Download based on your OS:

OS What to getMac MacTeXWindows Tex LiveLinux Tex Live (probably)

2. Use the VS Code integrated terminal from inside the documentation root directory, with the LaTeX builder:

make latex

3. Temporarily create a conda environment that you won’t need again

conda create -n PDF perl

4. Activate the PDF environment, then navigate to _build/latex:

make

Tip: You may need to do this a few times since it can take a few passes to resolve all the internal references.Just type enter if you get queried at all

Managing references

Contents

• Using Intersphinx

• Referencing external links

– xref

– extlinks

• Checking links

• Updating labels

62 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

• Referencing books

Using Intersphinx

Table 77: Select reference within AAAAAAReference topicIntersphinx Conceptual explanation

Table 78: Select referencesReference Topicsphinx.ext.intersphinx Official documentationIntersphinx reference syntax Syntax explanationIntersphinx inventory parser For linking to large projects

1. Locate the project’s objects.inv mapping, using the VS Code integrated terminal:

python -msphinx.ext.intersphinx http://www.sphinx-doc.org/en/master/objects.inv

• You may have to experiment with the project base URL. Some common endings:

– org/en/master/

– .io/en/latest/

– .com/en/latest/

2. Add the project’s base URL to the intersphinx_mapping dictionary in conf.py:

intersphinx_mapping = {'python': ('https://docs.python.org/3', None),'sphinx': ('http://www.sphinx-doc.org/en/master/', None),'pytest': ('https://docs.pytest.org/en/latest/', None),'rtfd': ('https://docs.readthedocs.io/en/latest/', None),'rtd-sphinx-theme':

('https://sphinx-rtd-theme.readthedocs.io/en/latest/', None),...

3. Inspect the objects.inv mapping from the project in question

• For large outputs, consider using a command line instead of the VS Code integrated terminal (but makesure to use a6)

4. Locate the desired target in the output and link to it using a corresponding role:

Table 79: Referencing select outputsCategory in objects.inv Role to usestd:doc :doc:rst:directive :rst:dir:std:label :ref:

5. Webpages of documentation, under std:doc, are arranged like the project’s table of contents, so you canfigure out the role target from the URL that a browser displays for the particular webpage. Consider https://docs.python.org/3/tutorial/introduction.html:

4.6. Procedures 63

AAAAAA Documentation, Release 0.4.0

Table 80: URL decompositionPortion Interpretation In role targethttps://docs.python.org/3/ Base URL python:tutorial/introduction.html Desired webpage tutorial/introduction

6. You can optionally define your own role title:

Listing 6: An Informal Introduction to Python

:doc:`python:tutorial/introduction`

Listing 7: A most beauteous tutorial

:doc:`A most beauteous tutorial <python:tutorial/introduction>`

7. Add a description of the link to links

8. Add a role to documentation using the appropriate capitalization:

Listing 8: Read about Sphinx roles

Read about :doc:`Sphinx roles <sphinx:usage/restructuredtext/roles>`

Note: When possible, use :ref: instead of :doc:, because the project’s toctree may change

See also:

Intersphinx with NumPy/Matplotlib has instructions for referencing NumPy and Matplotlib, though standard proce-dures from above are usually sufficient for AAAAAA

Referencing external links

Contents

• xref

• extlinks

For links that can not be managed with Intersphinx, use either xref or extlinks. In general you can use xref , but if thewebpage you want to cite comes from a website that you often use, it makes sense to use extlinks:

1. Wikipedia articles, like https://en.wikipedia.org/wiki/Download:

Listing 9: Resultant role

:wiki-pg:`Download`

2. RealPython tutorials, like https://realpython.com/python-type-checking:

64 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

Listing 10: Resultant role

:real-py:`python-type-checking`

3. Even Stack Overflow questions, like https://stackoverflow.com/questions/1441010/the-shortest-possible-output-from-git-log-containing-author-and-date:

Listing 11: Resultant role

:stack-q:`https://stackoverflow.com/questions/1441010/the-shortest-possible\-output-from-git-log-containing-author-and-date<1441010/the-shortest-possible-output-from-git-log-containing-author-and-\date>`

• Note that this works, but there may not be syntax highlighting in the above code-block because of the\-escapes for new lines

• This is still in compliance with line breaking standards

xref

Table 81: Select reference within AAAAAAReference topicxref Conceptual explanation

Table 82: Select referenceReference TopicSphinx xref extension User manual

1. Add your URL to the xref_links dictionary in conf.py, below the delimeter-style comment that reads Newlinks below, sorted links above

xref_links = {'Python': ('Python', 'https://www.python.org'),...'semver': ("Semantic Versioning", 'https://semver.org/'),# New links below, sorted links above'ottobib': ('OttoBib', 'https://www.ottobib.com'),

}

2. Add a link role to .rst files using the appropriate capitalization and an optional role title:

Listing 12: Python

:xref:`Python`

Listing 13: Python.org

:xref:`Python.org <Python>`

3. Add a description of the URL to links

• After this step, the URL can be moved above the delimiter-stye comment from conf.py

4.6. Procedures 65

AAAAAA Documentation, Release 0.4.0

Optimality considerations

• As long as URLs aren’t put above the delimiter-stye comment until after they are put into links, URLs can besorted in reasonably sized batches

• If you put a link in .rst files and in links first, you can bypass the delimiter-stye comment altogether when addingto conf.py

extlinks

Table 83: Select reference within AAAAAAReference topicextlinks Conceptual explanation

Table 84: Select referencesReference Topicextlinks Official documentationUsing a references extension Related configuration and usage

1. Add your base URL to the extlinks dictionary in conf.py, with a %s at the end:

extlinks = {'wiki-pg': ('https://en.wikipedia.org/wiki/%s', ''),'real-py': ('https://realpython.com/%s', ''),...

}

2. After you have added the base URL, you will then have access to a new custom role:

Listing 14: Yields Internet

:wiki-pg:`Internet`

Listing 15: Yields download

:wiki-pg:`download <Download>`

Note: The link checker is particular about capitalization for Wikipedia, so make sure to use the exact stringfrom the end of the URL: Download, not download

3. For most websites other than Wikipedia, you will usually want to add in a role title:

Listing 16: Yields python-type-checking

:real-py:`python-type-checking`

66 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

Listing 17: Yields type checking guide

:real-py:`type checking guide <python-type-checking>`

4. Add a description of the URL to links, then add your custom role to documentation using the appropriatecapitalization

Tip: Although you could use extlinks to create a URL that is not actually associated with a webpage, the link checkingprocedure will identify such errors

Checking links

Per Carol Willing’s Practical Sphinx talk from PyCon 2018:

1. From inside the documentation root directory, use the VS Code integrated terminal:

make linkcheck

Updating labels

1. With an active build running, open the VS Code integrated terminal from inside the documentation root directory

2. Use Intersphinx on _build/html/objects.inv to inspect inspect labels for AAAAAA

3. Verify the proper label style

4. Update any labels via the VS Code Command Palette

• Search: Replace in Files

Referencing books

Table 85: Select references within AAAAAAReference TopicBibTeX Conceptual explanationrefs.bib Collection of BibTeX-style citations

Table 86: Select referencesReference TopicBook Information sourceBibTeX Citation formatBibTeX extension Converts BibTeXOttoBib Get BibTeX for your bookISBN Unique identifier for booksBibTeX Entry and Field Types Syntax specificationsConvention for citing multiple authors Use of et. al

1. Check OttoBib for your ISBN and copy-paste the BibTeX option into refs.bib

4.6. Procedures 67

AAAAAA Documentation, Release 0.4.0

2. Verify that you added a book entry in refs.bib

• A book entry requires at least author (or editor), title, publisher, and year fields

• Consider et. al conventions for multiple authors

3. Add a role to books via :cite:`bib-book-name`

• Use a heading so that toctree can index the entry

• Use a label that starts with book- in books, and with bib- in refs.bib

.. _book-on-managing-yourself:

********************On Managing Yourself********************

.. csv-table:: :cite:`bib-on-managing-yourself`:align: center:header: Page(s), Topic

@Book{bib-on-managing-yourself,author = {Clayton M. Christensen et. al},title = {HBR's 10 Must Reads: On Managing Yourself},publisher = {Harvard Business Review Press},year = {2010},address = {Boston, Massachusetts},isbn = {978-1-4221-5799-2}}

Tip: The BibTeX extension is unreceptive to role titles

4.6.5 Napoleon

Table 87: Select reference within AAAAAAReference TopicNapoleon Conceptual explanation

Contents

• Adding a new module

• Referencing Python components

• Documenting variables

Adding a new module

1. The first time you add a new module, make sure to use automodule, even if you don’t want to describeeverything it contains:

68 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

Listing 18: AAAAAA.ledger

.. automodule:: AAAAAA.ledger:members: Transaction

Listing 19: conf

.. automodule:: conf:no-members:

2. This way, the module index will include the new module

Referencing Python components

1. Use the Python domain to create references:

Listing 20: AAAAAA.ledger.Transaction

:py:class:`AAAAAA.ledger.Transaction`

Listing 21: conf.html_theme_options

:py:data:`conf.html_theme_options`

Documenting variables

1. Use autodata to create E4 for variables, but make sure to use an empty annotation directive option if theattribute has a lot of characters in the source code:

Listing 22: Compare conf.html_theme and conf.html_theme_options

.. autodata:: conf.html_theme

.. autodata:: conf.html_theme_options:annotation:

• This will prevent rendering problems in the PDF version

Note: Make sure the variable has a docstring, even if it is empty, otherwise you will get a rendering problem

4.6.6 pytest

Table 88: Select reference within AAAAAAReference Topicpytest Conceptual explanation

4.6. Procedures 69

AAAAAA Documentation, Release 0.4.0

Discovering tests

1. Verify that you can use pytest in the VS Code integrated terminal from inside the AAAAAA project root directory,using a6

pytest

• This should yield output that looks like the pytest documentation

2. Use the VS Code Command Palette to select Python: Discover Unit Tests

1. If this fails, you may be experiencing a VS Code pytest issue that is associated with a new version of pytest.You can either:

1. Use the VS Code Insider Edition, if a fix has recently been made available

2. Temporarily use an older pop:

pop package-o-pytest, colloquially known as a pop

1. Activate the a6 environment

2. Use conda install with the appropriate syntax for the version number (taken from the conda cheat-sheet). For example:

conda install "pytest<=4.0.0"

3. Use the VS Code Command Palette to select Python: Discover Unit Tests

4. Check out the VS Code Test Explorer Extension to see if tests are showing up

4.6.7 Writing

Contents

• Creating a directory tree

• Documenting new topics

– Core conceptual topics

– Tools satellite topics

• Proofreading documentation

– Isolating changes

– New documents

– Changes to a document

Creating a directory tree

Adapted from directory tree sample code, to create the AAAAAA project tree:

1. Use the VS Code Command Palette to select File: New Untitled File

2. Copy and paste the below contents to the new file:

70 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

import os

base_indent = 4 * ' 'branch_symbol = '|-> 'where_to_start = '/Users/alnoki/Code/AAAAAA'

for root, dirs, files in os.walk(where_to_start):level = root.replace(where_to_start, '').count(os.sep)if level > 0:

indent = base_indent * (level - 1) + branch_symbolelse:

indent = ''print(f'{indent}{os.path.basename(root)}/')subindent = base_indent * (level) + branch_symbolfor f in files:

print(f'{subindent}{f}')

3. Modify base_indent and branch_symbol to symbols that you would like to have in your tree

4. Update where_to_start to the directory that you would like to write about

5. Select all the lines in the file

6. Use the Command Palette to select Python: Run Selection/Line in Python Terminal then type enter frominside the VS Code integrated terminal

Documenting new topics

Contents

• Core conceptual topics

• Tools satellite topics

Core conceptual topics

1. Gather necessary references first, preferably in a batch

• These should be concentrated at a centralized AAAAAA conceptual explanation, usually at tools

• Use 2 csv-tables of references at the central conceptual explanation

– The first containing links within AAAAAA

* See Sphinx for sample priority and nomenclature

– The second containing other references

.. csv-table:: Select references within :term:`AAAAAA`:align: center:header: Reference, Topic

:ref:`Developer environment <dev-env-intro>`, Setup:ref:`Sphinx configuration <configs-sphinx>`, Options:ref:`Sphinx procedures <procedures-sphinx>`, Usage...

(continues on next page)

4.6. Procedures 71

AAAAAA Documentation, Release 0.4.0

(continued from previous page)

.. csv-table:: Select references:align: center:header: Reference, Topic

:doc:`Sphinx <sphinx:intro>`, "Official:wiki-pg:`documentation <Software_documentation>`"...

2. Use a reference label in .rst files to refer to the core conceptual explanation

3. Update any relevant index.rst toctree descriptions, and potentially the what next? section

Tip: Avoid creating identical documentation in several places that must be multiply maintained

Tools satellite topics

1. Any new tools satellite topics, like configurations or procedures, should be reciprocally cross-referenced with aconceptual explanation, using reference tables

2. The new satellite topic should have at least a reference table with one link to a conceptual description in AAAAAA

.. csv-table:: Select reference within :term:`AAAAAA`:align: center:header: Reference, Topic

:ref:`tools-vs-code`, Conceptual explanation

3. If including other references outside of AAAAAA, add a second references table to the satellite topic

4. At the tools section, add a link to the satellite topic

5. Add a new conda package or update the Sphinx extension table, for example, if it makes sense for your newtopic

Proofreading documentation

Contents

• Isolating changes

• New documents

• Changes to a document

Tip: Read out loud in a marginally silly voice (to enhance your enjoyment of the content), and go slow

Isolating changes

This is typically done right before releasing a version

72 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

1. Use the VS Code Command Palette to GitLens: Compare Working Tree with Branch or Tag. . .

2. Select the tag of the relevant version to compare against

3. Proofread new documents and changed documents

• Even if you have moved an .rst file, GitLens is often able to identify that it is in a new directory and willonly display changes to the file (rather than classify it as new)

New documents

See documentation style for a list of things to watch out for

1. Open an autobuild in a browser alongside VS Code with maximum half-screen estate, so you can make editsimmediately

2. Go through one minor section at a time

1. Clear your browser history if you want to see which URLs you have not yet clicked

2. Read, out loud, the webpage that is rendered by your browser and make any corrections in VS Code

3. Verify each link in the section by clicking on it

4. Review the .rst file, especially parts that do not show up as white in the RST preview extension

5. When you see AAAAAA in the webpage, read it out loud as alnoki’s apps:

Table 89: GrammarYes NO!!!AAAAAA are splendid AAAAAA is doomed

Changes to a document

1. Compare against the last version using the VS Code Command Palette:

1. GitLens: Show File History

2. Choose from Branch or Tag History. . .

3. Select the tag that is most recent, then the commit that is most recent

4. Open Changes with Working File

Tip: If there is a warning that the file did not exist for that tag, then the file was probably moved

2. Compare: Toggle Inline View (optional)

3. Follow the procedures for proofreading new documents, but only review changes to the file by either:

• Move to Next Change

• Scrolling

4.6. Procedures 73

AAAAAA Documentation, Release 0.4.0

4.6.8 Versioning

Table 90: Select references within AAAAAAReference TopicVersions Conceptual explanationGit Version identificationRead the Docs Automated version supportDistributing documentation Walkthrough

Table 91: Select referencesReference TopicSemantic Versioning Numbering standardsGit commit guidelines Long version message guidelines

Contents

• Top-down to-do task deferral (TD)3

• Starting a new version

• Releasing a new version

Top-down to-do task deferral (TD)3

Table 92: Select references within AAAAAAReference topicOHIO Task management philosophyVS Code Task management environmentProject structure Layout

Table 93: Select referenceReference TopicMarkdown Syntax specification

Tip: Chant OHIO while doing this

1. Open TODO.md in VS Code

2. Use the VS Code symbol input to type:

• view outline

Table 94: Markdown headersLevel Meaning# Versions## Topic* Item

74 Chapter 4. Developer guide

AAAAAA Documentation, Release 0.4.0

3. Identify if the planned topic set is too much for one version

4. Starting with the topmost topic for the current version:

• Either defer the topic to the next version or move it to the bottom of the set for the current version

• Repeat until the topic that you started with is back at the top of the set for the current version

5. Re-order the topics in a logically progressive development sequence

6. Develop with a similar treatment of items/topics

• Start at the top and work your way down

• Re-ordering shouldn’t be necessary

• Either defer the item to a future version or complete it before moving on

Starting a new version

1. Create a new development branch named in accordance with semantic versioning standards: dev/MAJOR.MINOR.PATCH

2. In conf.py, update version numbers (and potentially copyright)

3. Add an entry to the version feature list

• Document changes as you go, in a way that tells the codebase what to do

4. Update the commit statistics and other data for the version that was just released at:

• The UTC on the version feature list

• version-stats.ipynb

• Verify the version statistics

5. Tidy up conda

6. Top-down to-do task deferral (TD)3

7. After you push, enable the development branch on your Read the Docs account

Releasing a new version

At this point you should be working on a development branch

1. Verify that the quickstart works

2. Verify and update directory trees

• AAAAAA

• Documentation

• Jupyter Notebooks

• Code

• Configurations

3. Update descriptions of any modified configurations

4. Update labels

5. Organize links so there are at most 10 URLs per list

4.6. Procedures 75

AAAAAA Documentation, Release 0.4.0

6. Finalize version feature additions

7. Isolate and proofread changes against the most recent release

• OHIO from the first .rst file to the last, editing only the .rst file you are on

• Feel free to add some to-dos for later, though

8. Do a link check

9. Get commit statistics and update:

• The date and time on the version feature list with 00:00:00Z

• Data for the version at version-stats.ipynb

– Increment the commit number from the commit statistics by 1

– Kernel -> Restart & Run All

– Verify the version statistics

10. Commit and push

11. Verify the build passes on your Read the Docs account

12. Merge the development branch in to the master branch

13. Tag and push with a long message that describes the version list additions

14. Use your Read the Docs account to disable the development branch and enable the new tag

76 Chapter 4. Developer guide

CHAPTER 5

Indices and tables

Here you can review contents of AAAAAA with precision and zeal!

5.1 Introduction

You can find a centralized list of acronyms from AAAAAA at AAACCC

See versions to review the development of AAAAAA

References contains an exhaustive list of links and books that are cited throughout AAAAAA

5.1.1 Automatic indices

Sphinx, the engine that generates documentation for AAAAAA, automatically creates the two entries below, which arehelpful for indexing documentation and software components in one place

You can view documentation for AAAAAA as a a website or as a PDF, and if you use the website version then youshould be able to access the two entries via a URL. If you are viewing a PDF version of AAAAAA, then they willappear at the end of the PDF

Table 1: Automatic indicesURL Componentsgenindex Everythingmodindex Just Python modules

5.2 Acronyms

AAACCC Alnoki’s Assimilated Acronyms: Centrally Collected and Counted (AAACCC or triple-Alfa triple-Charlie), colloquially known as alnoki’s acks, are not to be confused with alnoki’s apps

77

AAAAAA Documentation, Release 0.4.0

1. AAAAAA

2. AAACCC

3. AAA

4. AIPAIP

5. CCC

6. EEEE

7. OHIO

8. pop

9. PPP

10. TDTDTD

5.3 Versions

Versions of AAAAAA are numbered in accordance with semantic versioning standards, using ISO 8601 extended formatand UTC for time standards:

MAJOR.MINOR.PATCH (YYYY-MM-DDTHH:MM:SSZ)

Features are relevant to both users and developers alike, and usually include a relevant link to somewhere in AAAAAA.Modifications are explained in a way that tells the codebase what to do, like in commit messages

Statistics help measure the creation of content throughout the development of AAAAAA, using pandas! Because itis impractical to expect to know the UTC of a commit before it is made, that of the most recent version is given as00:00:00Z

Tip: If you manage your own Python package and you want to know how this is done, see the documentationdistribution guide and the versioning procedures

Contents

• Features

• Statistics

Table 2: Select referencesReference TopicSemantic Versioning Numbering standardsGit commit guidelines Long version message guidelinesISO 8601 Time standards

5.3.1 Features

• 0.4.0 (2019-03-21T00:00:00Z)

– Add to toctrees:

78 Chapter 5. Indices and tables

AAAAAA Documentation, Release 0.4.0

* Examples

* Developer guide intro

* Testing section

* Distribution section

* Documentation distribution guide

* Configurations

* Contributing setup

* AAACCC

* Version statistics

* Indices section

* VS Code procedures

* Napoleon procedures

– Add to tools section:

* Google

* Vim

– Integrate Vim with VS Code and recommend during developer environment setup

– Add PDF vs Website explanation

– Add extlinks support and procedures

– Add checklist explanation from The Checklist Manifesto

– Define time standards for versions

– Add reST syntax to sample-doc

– Add explanation of conf.py via napoleon, and assorted other configurations

• 0.3.1 (2019-02-17T19:41:19Z)

– Fix broken Read the Docs integration

• 0.3.0 (2019-02-17T18:45:27Z)

– Restructure toctrees

– Add versioning procedures

– Add BibTeX to create citations for books

– Add sphinx-autobuild support and associated procedures

– Add the spirit of alnoki’s apps

• 0.2.0 (2019-02-09T05:24:35Z)

– Add documentation for AAAAAA.ledger.Transaction via napoleon

• 0.1.0 (2019-01-31T02:57:50Z)

– Create website, using Sphinx, with notes on how to make a website, using Sphinx!

5.3. Versions 79

AAAAAA Documentation, Release 0.4.0

5.3.2 Statistics

AAA Aggregate Acronym Accrual (A3), the total count of alnoki’s acks, helps measure the creation of memory aidsin AAAAAA

PPP PDF Page Proliferation (P3), the number of pages in auto-generated documentation PDFs, helps measure theamount of content in a version

Table 3: Version statisticsTime of release Number Type # of commits PPP AAA2019-03-21 00:00:00+00:00 0.4.0 minor 133 116 102019-02-17 19:41:19+00:00 0.3.1 patch 98 69 72019-02-17 18:45:27+00:00 0.3.0 minor 96 69 72019-02-09 05:24:35+00:00 0.2.0 minor 77 51 32019-01-31 02:57:50+00:00 0.1.0 minor 67 45 2

5.4 References

5.4.1 Links

This is a centralized and comprehensive list of online information cited throughout documentation for AAAAAA, inUniform Resource Locator (URL) format

Links are not necessarily in order, but links with high priority are usually placed at the top of a section

Tip: If you manage a website using Sphinx and you want to create a list like this, see the references procedures

Contents

• Python

– General

– Project structure

– Text

– Types

– Control flow

– Classes

– Environments

* Anaconda

* Conda syntax

• Packages

– Numerical Analysis

* NumPy

* Matplotlib

80 Chapter 5. Indices and tables

AAAAAA Documentation, Release 0.4.0

* pandas

– pytest

• Project management

– AAAAAA codebase

– Versioning

– Distribution

• Git version control

– General

– Core commands

– Auxiliary commands

– Special features

• Documentation

– General

– Sphinx

* Practical use

* Usage specifics

* With Read the Docs

* Reference management

* Showing code

* Napoleon

– reStructuredText

* General

* Syntax

– Engine-agnostic formatting

• Tools

– Jupyter

* General

* Extensions

– VS Code

* General

* Colors

* Extensions

– Vim

* Official information

* Unofficial supplements

5.4. References 81

AAAAAA Documentation, Release 0.4.0

• Computers

– General

– Interfaces

– Software

– Syntax

– Data storage

– Time

– OS specifics

– The Internet

– Information sources

– Software design standards

• Financial

– Securities mechanics

– Money definitions

• Mathematics

• Philosophy

– Personal motivation

– Places worth visiting

Python

General

1. Corey Schafer YouTube playlist: Python Tutorials

• Recommended starting point for learning Python

2. Python.org

• Definitive reference for the Python

3. The Python Tutorial

• Official Python tutorial

4. PEP 8

• Official Python style guide for source code

5. Functional Programming HOWTO

• Official tutorial on Python techniques

6. Python HOWTOs

• Official in-depth Python tutorials for various advanced topics

7. Python Frequently Asked Questions

• In-depth answers to specific questions about core functionality

82 Chapter 5. Indices and tables

AAAAAA Documentation, Release 0.4.0

8. Programming FAQ

• Syntax, methods, recommended practices

9. RealPython

• Comprehensive website with examples, guides, tips, etc.

10. Using the Python Interpreter

• Instructions for the mechanism that runs Python code

Project structure

1. Packages

• Structuring of source code and directories in a project

2. Printing a directory tree

• Sample code to make a directory tree

• Adapted for the directory tree procedure

3. pip

• General installer for packages

• Used to configure a6 for use with pytest

4. Module

• A file that ends with a .py extension

Text

1. Python quote convention

• Recommendation for using ' vs " in strings

2. Comments

• Documentation inside source code

3. Documentation Strings

• Comments for specific Python components

4. print()

• Display a string

Types

1. Built-in Types

• Standard Python data structures

2. Object

• The most basic type, from which others are derived

3. Dictionaries

5.4. References 83

AAAAAA Documentation, Release 0.4.0

• A type containing key: value pairs

4. RealPython guide to type checking

• How to verify correct types in source code

5. Numbers

• Simple introduction to int and float

6. int

• A number like 2 or 128 but not 2.3

7. float

• A number like 1.5 or 3.0 but not 3

8. Decimals

• A precise way to represent things like money

9. Floating Point Arithmetic: Issues and Limitations

• When to use decimals instead of floats

Control flow

1. Functions

• Processes that can act on arguments

2. Default Argument Values

• Values that must be passed to a function

3. Keyword Arguments

• Values that may be (but do not need to be) passed to a function

4. Argument

• Concise definition for both positional and keyword styles

Classes

1. Classes

• A way to bundle data and functionality together

2. Class Objects

• Syntax and instance concepts, like __init__()

3. Attributes

• Accessed via dotted notation: big_thing.small_attribute

4. Python Scopes and Namespaces

• Domains of association

5. Class and Instance Variables

• Attributes of a class that have different scopes

84 Chapter 5. Indices and tables

AAAAAA Documentation, Release 0.4.0

6. property

• A special attribute of a class which can be a function instance variables

• AAAAAA.ledger.Transaction.per_share_amount is a property

Environments

Anaconda

1. Anaconda

• A manager for Python packages

2. Anaconda Distribution

• Official documentation

3. Miniconda

• Small manageable version of Anaconda

4. Conda

• Command line configurator for Anaconda

5. Starting conda

• Invocation methods for conda

6. Conda package

• Python package managed by Anaconda

7. Conda environment

• A collection of conda packages

8. Conda channel

• A host for conda packages

9. conda-forge

• A community-driven conda channel

Conda syntax

1. Conda cheatsheet

• Common commands for conda

2. conda create

• Make a new conda environment

3. conda install

• Add a package to a conda environment

4. Activating an environment

• Enable use of a conda environment

5. Managing environments

5.4. References 85

AAAAAA Documentation, Release 0.4.0

• Using environment files

6. conda clean

• Removing unnecessary conda packages

7. conda update

• Get the most recent version of conda packages

8. conda list

• List the conda packages in a conda environment

Packages

Numerical Analysis

NumPy

1. NumPy

• Fundamental package for advanced numerical Python

2. Quickstart tutorial

• Official NumPy tutorial

3. codebasics NumPy tutorial

• Recommended NumPy tutorial on YouTube

Matplotlib

1. Matplotlib

• Plotting tool for numerical data

2. Tutorials

• Instructions to use Matplotlib

3. codebasics Matplotlib tutorial

• Recommended Matplotlib tutorial on YouTube

pandas

1. pandas

• For handling datasets

2. 10 Minutes to pandas

• Official pandas tutorial

3. codebasics pandas tutorial

• Recommended pandas tutorial on YouTube

86 Chapter 5. Indices and tables

AAAAAA Documentation, Release 0.4.0

pytest

1. pytest

• Framework for writing test code

2. codebasics pytest tutorial

• Recommended pytest tutorial on YouTube

3. pytest tutorials

• Official comprehensive pytest walkthroughs

4. Good Integration Practices

• Configuring pytest to run with a6

5. VS Code pytest issue

• A potential problem (and solution) when using Visual Studio Code with pytest

Project management

AAAAAA codebase

1. AAAAAA repository

• GitHub repository for AAAAAA

2. alnoki’s GitHub repositories

• Assorted Jupyter Notebooks and code from other tutorials

3. GitHub

• Online repository for software projects

4. AAAAAA repository archive

• Quickly download the AAAAAA repository

Versioning

1. Semantic Versioning

• Version number guidelines: MAJOR.MINOR.PATCH

2. Git commit guidelines

• General guidelines for describing contributions to a project

3. Git commit message style

• Specific language style for contributing to a project

4. Minimum Viable Prototype (MVP)

• An incremental way to create or add features

5.4. References 87

AAAAAA Documentation, Release 0.4.0

Distribution

1. Requirements Files

• Help Read the Docs identify Sphinx extensions

2. Packaging Python Projects

• Create a Python package

Git version control

General

1. Version control

• A way to track changes to files

2. Git manual

• Quick practical reference

3. Git book

• In-depth conceptual explanations

4. downloads

• Get Git

5. Git setup

• Getting started

6. SHA-1

• Unique identifier attached to each commit

7. .gitignore

• Ignore certain files

8. less pager

• For viewing git-log

Core commands

1. git-clone

• Download a software project

2. git-config

• Setup user credentials

3. git-log

• See project history

4. git-commit

• Create saved changes to a project

5. git-add

88 Chapter 5. Indices and tables

AAAAAA Documentation, Release 0.4.0

• Prepare changes for committing

6. git-push

• Upload a commit

7. git-tag

• Assign a special identifier to a commit

8. git-branch

• Work with independent sequences of commits

9. git-checkout

• Switch between branches

10. git-merge

• Combine branches

Auxiliary commands

1. git-reset

• Fix mistakes

2. git-show

• Inspect tags and commits

3. git-rev-list

• Get number of commits

Special features

1. Git log formatting options

• Special options for inspecting git-log

2. Listing Git project developers

• Identifying unique committers

3. GitHub.com instructions to change author history

• GitHub instructions to re-write git-commit history

4. Git filter-branch options

• Extra options for re-writing commit history

Documentation

General

1. Python Developer’s Guide to Documenting Python

• Guide to general Sphinx use

• reStructuredTest style guide

5.4. References 89

AAAAAA Documentation, Release 0.4.0

2. RealPython guide to documenting Python

• Recommended documentation practices for Python

3. Acronym

• A short way to say something, like AAAAAA

4. Citation

• A way to create a reference to a source of information

5. Book

• Information source

6. ISBN

• Unique identifier for books

7. Convention for citing multiple authors

• Use of et. al

8. Copyright

• Defines rules for using content

Sphinx

Practical use

1. Sphinx

• Official documentation for the Sphinx engine, which creates documentation

2. Sphinx quickstart tutorial

• How to start a new documentation project

3. Matplotlib sampledoc tutorial

• Quick walkthrough with practical syntax examples

• Interactive Python examples, using plots

4. Carol Willing’s Practical Sphinx talk from PyCon 2018

• Common development tasks1, like checking links

• Team development strategies

5. Sphinx builders

• Create different styles of documentation

1

Time in video Topic10:15 Incorporating Jupyter Notebooks13:00 Checking spelling14:00 Incorporating images15:15 Including code17:00 Continuous integration20:00 Autodoc24:15 Themes

90 Chapter 5. Indices and tables

AAAAAA Documentation, Release 0.4.0

6. sphinx-autobuild

• Automatically update documentation builds

7. Intro to Sphinx and Read the Docs

• General explanation of using Read the Docs with Sphinx

• From Eric Holscher, co-founder of Read the Docs

8. HTTP server

• Python package that can host a website for viewing documentation

Usage specifics

1. Extensions

• Additional Sphinx functionality

2. conf.py usage

• How to configure a Sphinx project

3. Table of contents

• Directive for creating project documentation structure

4. Autodoc extension

• Sphinx extension for generating documentation directly from source code

5. Use the External Links Extension

• Instructions for installing an example Sphinx extension

• Similar to external link management in AAAAAA

6. math

• Role for using LaTeX in-line

7. math

• Directive for using LaTeX on its own line

8. HTTP socket error fix

• Potential problem (and solution) when building documentation

9. Domains

• Collection of directives and roles for specific topics

10. File-wide metadata

• Enable orphan pages, like sample-doc.rst

With Read the Docs

1. Mahdi Yusuf’s Sphinx & Read the Docs screencast

• Setting up a project using quickstart

• toctree and associated documentation structure

5.4. References 91

AAAAAA Documentation, Release 0.4.0

• Basic reST syntax

2. Read the Docs

• Online repository for software documentation

3. Read the Docs with Sphinx

• Tutorial for starting a Sphinx project hosted on Read the Docs

4. Read the Docs Sphinx Theme

• Contains sample reST syntax

5. Read the Docs Sphinx Theme configuration

• Values to use in conf.py

6. Webhooks

• Automatic project modification detection

7. Versions

• Automatic support for versions

8. Build Process

• How the host computer performs Sphinx build procedures for Read the Docs

9. Read the Docs account

• Interface for distributing documentation

Reference management

1. Intersphinx extension

• Official documentation

• For linking to other Sphinx projects

2. Michael Jones’ xref extension

• Sphinx extension to manage common links in a project

3. extlinks

• Sphinx extension for URLs from common sources

4. Intersphinx objects.inv explanation

• Interpretation of objects.inv when using Intersphinx

5. Intersphinx inventory parser

• Sample code for analyzing objects.inv maps

6. Intersphinx with NumPy/Matplotlib

• Instructions for using Intersphinx with specific packages

7. BibTeX

• Citation management format

8. BibTeX extension

• Sphinx extension for citing with BibTeX

92 Chapter 5. Indices and tables

AAAAAA Documentation, Release 0.4.0

9. OttoBib

• Provides BibTeX data for a book with a given ISBN

10. BibTeX Entry and Field Types

• Syntax for identifying specific citation components

Showing code

1. code-block

• Directive to show sections of code

2. literalinclude

• Directive to show sections of code, directly from a file

3. Type annotations

• Syntax to indicate types in code

4. Python roles

• Sphinx Domain for Python component documentation

5. Read the Docs sample Python module

• Sample syntax for autodoc

6. Info field lists

• reST syntax shown at Elaborately Embellished Explanatory Enhancements (E4)

Napoleon

1. Napoleon

• Sphinx extension to include content from NumPy docstrings

2. Autodoc

• Sphinx extension to include content from docstrings

3. PEP 257

• Official conventions for docstrings

4. NumPy docstrings

• Docstring format provided by NumPy

5. Example NumPy Style Python Docstrings

• Sample NumPy docstring syntax for napoleon

6. automodule

• Show modules

7. autodata

• Show attributes

8. autofunction

• Show functions

5.4. References 93

AAAAAA Documentation, Release 0.4.0

reStructuredText

General

1. reStructuredText Primer

• Sphinx explanation of reST, a particular markup language

2. reStructuredText

• Official documentation

3. Quick reST

• Official reference with reST examples

4. Doc8 reST linter

• Linter for reST

Syntax

1. reST cheatsheet

• Quick reference for reST usage

2. reST list indentation

• Syntax tip

3. Tables

• Syntax options

4. Role

• Element that marks a piece of text, usually in-line

5. Directive

• Element that marks a block of text

6. guilabel

• Fancy buttons

7. Label role

• Role syntax to link to arbritrary documentation locations

8. Admonition

• A special badge of text2

2

Danger: This is an admonotion

94 Chapter 5. Indices and tables

AAAAAA Documentation, Release 0.4.0

Engine-agnostic formatting

1. Tables generator for assorted languages

• Online tool to format tables in LaTeX, Markdown, reStructuredText, and plain text

2. LaTeX

• System for documentating equations in Jupyter Notebooks and in Sphinx

3. Markup language

• A way to create documentation in a computer

4. Markdown

• Markup language used to generate tables, lists, and other components

• Used for GitHub, Jupyter Notebooks, and AAAAAA task management

5. NATO phonetic alphabet

• A: Alfa, B: Bravo, and so on

Tools

Jupyter

General

1. Jupyter Notebooks

• Interactive Python environment

• Code, LaTeX, Markdown, and plotting in one file

2. Corey Schafer tutorial

• Recommended for learning to use Jupyter Notebooks

• Tutorial video from Corey Schafer

3. Jupyter Notebook viewer for AAAAAA

• Online viewer for Jupyter Notebooks in AAAAAA

Extensions

1. Unofficial Jupyter Notebook Extensions

• Additional functionality for Jupyter Notebooks

2. Collapsible Headings

• Section navigation and management

3. Table of Contents (2)

• Automatic section linking

4. Variable Inspector

• Inspect data values

5.4. References 95

AAAAAA Documentation, Release 0.4.0

5. Live Markdown Preview

• Preview Markdown and LaTeX

VS Code

General

1. Integrated development environment (IDE)

• Software that is used to make software

2. Visual Studio Code

• An IDE that is open-source

• Has a collection of extensions developed by the open-source community

3. Extensions

• Enable additional functionality

4. VS Code Python tutorial

• Setup and basic usage

5. VS Code unit testing

• Use pytest

6. VS Code settings

• Configurations in settings.json

7. User interface

• Explanation of core components

8. VS Code integrated terminal

• Use a command line

9. VS Code Command Palette

• Direct command input

10. Insider Edition

• Has the latest features, may have problems

Colors

1. Themes

• General colors for the IDE

2. Token color customizations

• Reference for changing specific colors

3. Color theme extension guide

• Enhanced color customization functionality

4. Token color customizations usage

96 Chapter 5. Indices and tables

AAAAAA Documentation, Release 0.4.0

• Advanced color manipulation

Extensions

1. Managing extensions

• Official documentation

2. GitLens

• Enhanced Git functionality

3. Python

• Work with Python

4. Selecting the Python interpreter

• Integrate the Python interpreter

5. Python Test Explorer Extension

• Use pytest

6. VS Code Bookmarks extension

• Mark and navigate source code

7. reStructuredText

• Syntax highlighting for reStructuredText

• Limited live rendering functionality

8. Doc8 newline issue fix

• Fix for syntax highlighting problem in reStructuredText extension

9. Vim extension for VS code

• Use Vim in VS Code

Vim

Official information

1. Vim text editor

• For git-config, git-commit, and VS Code

2. Mac OS syntax highlighting

• Enable syntax highlighting

3. .vimrc file

• Vim configuration file for syntax highlighting

4. Repeating keystrokes

• Do similar commands repeatedly

5. Official tutorial

• Simple instructions

5.4. References 97

AAAAAA Documentation, Release 0.4.0

6. All the right moves

• Intermediate command reference

Unofficial supplements

1. Interactive Vim tutorial

• Learn Vim

2. Vim cheatsheet

• Common commands for Vim

3. Mastering Vim by Chris Toomey

• Demonstrative video with tips and commands

4. Vim E325 error

• Can happen when committing incorrectly

5. How to Learn Vim

• Become efficient with Vim text editor

Computers

General

1. Computer

• A system that manipulates information using software

2. User

• Who is using software

3. Developer

• Who is creating software

4. Install

• Provide software for a computer

Interfaces

1. Mobile device

• A small, portable computer

2. Laptop

• A portable computer

3. Copy-paste

• One way to share source code

4. Typing

• How to create strings

98 Chapter 5. Indices and tables

AAAAAA Documentation, Release 0.4.0

5. Web colors

• Colors for the Internet

6. Point and click

• One way to use a computer

7. Rendering

• Creating visualizations on a computer

8. Scrolling

• Moving visualizations around

9. Sidebar

• Keeps information on the side of a program

10. Button

• A component that you can click

Software

1. Source code

• A way to communicate with a computer

2. Software

• A structured collection of source code

3. Open-source software

• Public way to share source code

4. Software documentation

• Describes how software works

5. Development

• Making software

6. Line of code

• One portion of source code

7. Algorithm

• A software process

8. Linter

• Check source code for syntax or style errors

9. Execution

• When a computer uses software

5.4. References 99

AAAAAA Documentation, Release 0.4.0

Syntax

1. Syntax

• String composition rules

2. Syntax highlighting

• Rendering for special components in a file

3. Character

• Usually, a text symbol

4. String

• How a computer stores characters

5. Line

• A sequence of characters

6. Line break

• A way to indicate the end of a line

7. Whitespace

• A way to separate characters

8. Indentation

• One style of whitespace

9. Delimiter

• A data boundary marker

Data storage

1. Directory

• Cataloging structure for computer data

2. File

• A way to store data in a computer

3. Path

• Identifier for a directory or file

4. Filename extension

• A way to identify a type of a file

5. PDF

• A general document filetype

100 Chapter 5. Indices and tables

AAAAAA Documentation, Release 0.4.0

Time

1. Time

• The passage of events

2. Time standard

• A way to measure time

3. ISO 8601

• A specific time standard

4. UTC

• A time standard that works with ISO 8601

5. DenCode

• Convert between time standards

OS specifics

1. Operating System

• Computer resource manager

2. Mac OS

• A common operating system

3. Mircosoft Windows

• A common operating system

4. Linux

• A common operating system, which is open-source

5. Linus Torvalds interview

• Creator of Linux

• Cited at the spirit of alnoki’s apps

6. Command line

• A direct way to communicate with an operating system

7. cmd.exe

• Command line for Windows

8. bash

• Command line for Mac and Linux

9. Cyberciti.biz instructions to change bash prompt

• How to change bash prompt to a custom string like $

10. Exit status

• A report from software when it is done

5.4. References 101

AAAAAA Documentation, Release 0.4.0

The Internet

1. Internet

• An interconnected system of computers and information

2. Website

• A way to view content on the Internet

3. Web browser

• A viewer for a website

4. Web browsing history

• Identify links you have not clicked

5. Webpage

• What a web browser shows

6. Hypertext Markup Language (HTML)

• Standard markup language for webpages

7. Uniform Resource Locator (URL)

• A way to identify a webpage

8. Download

• Gather information from the Internet

9. Upload

• Provide information to the Internet

10. Host

• A computer that provides resources to other computers via the Internet

Information sources

1. Search engine

• A software system that indexes Internet information

2. Google

• Preferred search engine

3. Wikipedia

• Preferred source of online information

4. YouTube

• For accessing tutorials and other video information

5. Stack Overflow

• Community website that provides answers to computer questions

102 Chapter 5. Indices and tables

AAAAAA Documentation, Release 0.4.0

Software design standards

1. 219 Design

• Smart product design consulting firm

2. DO-178B

• Software design standards for aviation devices

3. Attitude Heading and Reference System (AHRS)

• Aviation device, sometimes DO-178B Level A

4. Garmin Ltd.

• Manufacturer of DO-178B Level A aviation products

5. _why’s (Poignant) Guide to Ruby, Chapter 3

• Explanation of software, mentioned in Alnoki’s Inspired Philosophies, Adopted and Implemented in Prac-tice (AIP)2

Financial

Securities mechanics

1. Corporation

• An organization that acts as a single entity

2. Share

• A single unit representing fractional ownership

3. Stock

• The combination of all shares that form representative ownership of a corporation

4. Financial asset

• A non-physical asset, like shares of stock

5. Securities

• Tradable forms of financial assets

6. Brokerage

• Facilitates the buying and selling of securities

7. Ticker symbol

• Identifier used to buy or sell a security through a brokerage

8. Dividend

• Typically, money that a corporation pays to its shareholders

5.4. References 103

AAAAAA Documentation, Release 0.4.0

Money definitions

1. Finance

• The management of money

2. Medium of exchange

• A widely accepted token that can be exchanged for something else

3. Money

• An item or verifiable record that is accepted as a medium of exchange

4. Financial transaction

• Typically, an exchange of money for something else

5. United States dollar

• A unit of money

6. Cent

• 1100 of a basic money unit

7. Fee

• An amount of money paid for services

8. Bank

• An institution that manages money

Mathematics

1. Factorial

• 𝑥! = 𝑥(𝑥− 1)(𝑥− 2)...

2. MacTeX

• LaTeX for Mac

3. Tex Live

• LaTeX for Windows (and probably Linux)

Philosophy

Personal motivation

1. Corey Schafer interview from RealPython

• Reasons for making content

• Cited in Alnoki’s Inspired Philosophies, Adopted and Implemented in Practice (AIP)2

2. Why quantity trumps quality

• Just keep making content

• Cited in Alnoki’s Inspired Philosophies, Adopted and Implemented in Practice (AIP)2

104 Chapter 5. Indices and tables

AAAAAA Documentation, Release 0.4.0

Places worth visiting

1. NASA Marshall Space Flight Center Flight Robotics Laboratory

• Flight testing procedures cited in Alnoki’s Inspired Philosophies, Adopted and Implemented in Practice(AIP)2

2. Caye Caulker

• Island with the mantra go slow, cited in Alnoki’s Inspired Philosophies, Adopted and Implemented inPractice (AIP)2

5.4.2 Books

This is a centralized and comprehensive list of books that are cited throughout AAAAAA. Citations are managed usingBibTeX, according to book reference procedures

Note: If you are viewing the website form of AAAAAA documentation, the bibliography for these books should be onthis webpage. If you are viewing the PDF form of AAAAAA documentation, it should appear towards the end

Books

• On Managing Yourself

• The Checklist Manifesto

On Managing Yourself

Table 4: [bib-on-managing-yourself]Page(s) Topic82 , 91 OHIO

OHIO Only handle it once (OHIO) is a task management habit used to plan development tasks in AAAAAA. From OnManaging Yourself :

With paperwork, apply the OHIO (“Only handle it once”) rule: Whenever you touch a document, acton it, file it, or throw it away

The Checklist Manifesto

Table 5: [bib-checklist-manifesto]Page(s) Topic13 Why use a checklist?

checklist From The Checklist Manifesto:

Here, then, is our situation at the start of the twenty-first century: We have accumulated stupendousknow-how. We have put it in the hands of some of the most highly trained, highly skilled, andhardworking people in our society. And, with it, they have indeed accomplished extraordinary things.Nonetheless, that know-how is often unmanageable. Avoidable failures are common and persistent,

5.4. References 105

AAAAAA Documentation, Release 0.4.0

not to mention demoralizing and frustrating, across many fields - from medicine to finance, businessto government. And the reason is increasingly evident: the volume and complexity of what weneed to know has exceeded our individual ability to deliver its benefits correctly, safely, or reliably.Knowledge has both saved us and burdened us.

That means we need a different strategy for overcoming failure, one that builds on experience andtakes advantage of the knowledge people have but somehow also makes up for our inevitable humaninadequacies. And there is such a strategy - though it will seem almost ridiculous in its simplicity,maybe even crazy to those of us who have spent years carefully developing ever more advanced skillsand technologies.

It is a checklist.

See also:

Have you tried that new dish from the f00cafe?

106 Chapter 5. Indices and tables

Bibliography

[eta10] Clayton M. Christensen et. al. HBR’s 10 Must Reads: On Managing Yourself. Harvard Business Review Press,Boston, Massachusetts, 2010. ISBN 978-1-4221-5799-2.

[Gaw10] Atul Gawande. The Checklist Manifesto: How To Get Things Right. Metropolitan Books, New York, 2010.ISBN 978-0-312-43000-9.

107

AAAAAA Documentation, Release 0.4.0

108 Bibliography

Python Module Index

aAAAAAA.ledger, 8

cconf, 41

109

AAAAAA Documentation, Release 0.4.0

110 Python Module Index

Index

Aa6, 18AAA, 80AAAAAA, 1AAAAAA.ledger (module), 8AAACCC, 77author (in module conf ), 42

Cchecklist, 105conf (module), 41copyright (in module conf ), 42

Ddescription (AAAAAA.ledger.Transaction attribute),

9

Eepub_exclude_files (in module conf ), 43epub_title (in module conf ), 43exclude_patterns (in module conf ), 43explanation() (built-in function), 37extensions (in module conf ), 42extlinks (in module conf ), 44

Hhtml_static_path (in module conf ), 43html_theme (in module conf ), 43html_theme_options (in module conf ), 43htmlhelp_basename (in module conf ), 43

Iintersphinx_mapping (in module conf ), 44

Kkind (AAAAAA.ledger.Transaction attribute), 8kinds (AAAAAA.ledger.Transaction attribute), 9

Llatex_documents (in module conf ), 43latex_elements (in module conf ), 43linkcheck_ignore (in module conf ), 43

Mman_pages (in module conf ), 43master_doc (in module conf ), 43

Nnum_shares (AAAAAA.ledger.Transaction attribute), 8

OOHIO, 105

Pper_share_amount (AAAAAA.ledger.Transaction at-

tribute), 9pop, 70PPP, 80project (in module conf ), 42Python Enhancement Proposals

PEP 257, 37PEP 484, 24, 37PEP 8, 18, 37

Python Enhancement ProposalsPEP 257, 93PEP 484, 24, 37, 93PEP 8, 32, 46, 82

Rrelease (in module conf ), 42

Ssymbol (AAAAAA.ledger.Transaction attribute), 8

Ttexinfo_documents (in module conf ), 43

111

AAAAAA Documentation, Release 0.4.0

total_amount (AAAAAA.ledger.Transaction at-tribute), 8

Transaction (class in AAAAAA.ledger), 8

Vversion (in module conf ), 42

Wwhen (AAAAAA.ledger.Transaction attribute), 8

Xxref_links (in module conf ), 44

112 Index