aaaaaa documentation - read the docs
TRANSCRIPT
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
• 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
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 [email protected]
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 = [email protected]
[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="[email protected]"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 [email protected] 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="[email protected]"OLD_EMAIL2="[email protected]"CORRECT_NAME="alnoki"CORRECT_EMAIL="[email protected]"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:
* 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