Greg Meece GLMeece

Sphinx Setup for autodoc

Sphinx is a documentation generator that is the de facto standard for Python projects. The official documentation can be a bit daunting as it includes so many options, it's hard to know where to start.

Note: This Gist was updated on 04/04/2019 to accomodate a newer version of Sphinx, as well as Python 3.7. YMMV!

This document is written with the following presuppositions:

You want to leverage the DocStrings in your Python code.
You'd rather write your DocStrings in Google-style instead of a more awkward reStructuredText format for calling documentation.

Virtual Environments

Before beginning, you should have a version of pip installed. If you don't, it is recommended you install it universally via the Terminal: sudo easy_install pip
Once you do, install virtualenvwrapper: sudo pip install virtualenvwrapper. More information can be found in Read the Docs
Change into the directory where your new project is; e.g., cd ~/Documents/Repos/my_new_project
Create your new environment in this directory, automatically giving it the name of the current directory: thisdir=${PWD##*/};mkvirtualenv -a . -r requirements.txt $thisdir

Using Your Virtual Environment

To make sure you remember what your virtual environment is named (and, indeed - all you have created), execute lsvirtualenv which lists all virtual environments.

pandoc -f docx -t markdown -o my_example_output.md my_example_input.docx

Steps to Terminal Enlightenment on a Mac

Hopefully you'll Live Long and Prosper, so I don't mean terminal as in "you gonna die". This is a somewhat opinionated article on configuring a macOS machine with:

iTerm2
Z-shell
Oh My ZSH! (mostly obsolete now)
Powerlevel9k
Nerd Fonts, which are Powerline-derived fonts, particularly my favorite - Hack Nerd

Useful Docker Cheat Sheet

Random Tips

If needed, create a .dockerignore file to exclude files/paths you don't want. Matching rules are from Golang's filepath rules, as well as some unique exceptions.

A Dozen Dockerfile Instructions to Know

FROM — specifies the base (parent) image; typically you specify both the image name as well as the label. 🍰
RUN — runs a command and creates an image layer. Used to install packages into containers. 🍰

Computer Language Case Styles

A quick discussion of the most popular ways to invoke variable (or constant) names using case and/or space replacement.

These styles are:

camelCase
PascalCase
snake_case
kebab-case

	http_bad_codes = {
	"400": "Bad Request",
	"401": "Unauthorized",
	"402": "Payment Required",
	"403": "Forbidden",
	"404": "Not Found",
	"405": "Method Not Allowed",
	"406": "Not Acceptable",
	"407": "Proxy Authentication Required",
	"408": "Request Timeout",

	"""Nice Title Case Function plus quick demo"""


	def nice_title_case(str_in: str) -> str:
	"""Converts a string to Title Case, with conventional exceptions which
	need not be capitalized if they are not the first word in the title.

	Reference: https://en.wikipedia.org/wiki/Title_case

	Note: Prepositional rules are not strictly enforced

	# It is assumed that $HOME is already defined and exported...

	# Assuming within our home directory,
	# we have a hidden directory called '.env'
	envvarsdir="/.env/"
	# ...and within that directory we had a file named 'secret_vars.ini'...
	envvarsfile=secret_vars.ini
	# ...we'd build the path
	envvarspath=$HOME$envvarsdir$envvarsfile

	# zmodload zsh/zprof # <-- enable for shell profiling

	# Note: for more options info, see:
	# https://gist.github.com/geeknam/4423298046c4383d36a91c404ff049b1

	# Autoload info:
	# With the -U flag, alias expansion is suppressed when the function is loaded.
	# -z mark the function to be autoloaded using the zsh style
	autoload -Uz compinit