Permalink
Browse files

Adding Sphinx-based documentation

  • Loading branch information...
1 parent 40b642b commit 14922c86a70972e04ec6ba1730f49ca3630a9738 Curt Merrill committed Jun 16, 2011
View
@@ -0,0 +1,130 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = _build
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " singlehtml to make a single large HTML file"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " devhelp to make HTML files and a Devhelp project"
+ @echo " epub to make an epub"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " text to make text files"
+ @echo " man to make manual pages"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+ -rm -rf $(BUILDDIR)/*
+
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json:
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/IRE-Census.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/IRE-Census.qhc"
+
+devhelp:
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/IRE-Census"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/IRE-Census"
+ @echo "# devhelp"
+
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through pdflatex..."
+ make -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ @echo
+ @echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ @echo
+ @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+changes:
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: f2adb26c4ce0ac96fa94035bb8ef848d
+tags: fbb0d17656682115ca4d033fb2f83ba1
@@ -0,0 +1,56 @@
+=============
+Data Overview
+=============
+
+The census.ire.org site will contain data from Summary File 1 of the 2010 Decennial Census. For full details about the data contained in these tables, please refer to Chapter 6 of the `Technical Documentation`_ provided by the Census Bureau.
+
+.. _Technical Documentation: http://www.census.gov/prod/cen2010/doc/sf1.pdf
+
+The Census Bureau is releasing the Summary File 1 data on a rolling basis beginning in mid June. Data for a few states will be released each week and added to the census.ire.org site until all data are available sometime in August.
+
+
+Geographies
+===========
+
+The census.ire.org site will provide data at several key levels of geography: place, county subdivision, county and state.
+
+Places and county subdivisions
+------------------------------
+
+Counties
+--------
+
+Counties in most states.
+
+Parishes in Louisiana.
+
+Alaska has boroughs, and county-equivalents for areas of the state not part of borough.
+
+
+States
+------
+
+Self explanatory.
+
+
+Formats
+=======
+
+CSV
+---
+
+These are comma-separated-value files. They are plain-text files that can be opened in Excel or other programs for further analysis of the data.
+
+The fields in the CSV files will be transposed.
+
+
+KML
+---
+
+File suitable for using with Google Fusion Table's mapping feature or other spatial analysis tools.
+
+JSON
+----
+
+Javascript Object Notation for use with web applications.
+
@@ -0,0 +1,23 @@
+.. IRE-Census documentation master file, created by
+ sphinx-quickstart on Fri Jun 10 11:26:35 2011.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Welcome to IRE-Census's documentation!
+======================================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 1
+
+ quickstart.rst
+ data.rst
+
+..
+ Indices and tables
+ ==================
+
+ * :ref:`genindex`
+ * :ref:`modindex`
+ * :ref:`search`
@@ -0,0 +1,59 @@
+========
+Tutorial
+========
+
+This tutorial is designed to walk you through
+the basic features of census.ire.org
+by using the site to answer a series of questions.
+
+Question 1: How does the racial/ethnic make-up of my town compare to my county and state?
+=========================================================================================
+
+.. note:: For the purposes of this tutorial, you live in Anniston, Alabama.
+
+When census.ire.org first loads, you'll be asked what geography level you're interested in.
+For a detailed explanation of these terms, please see <tk>.
+
+We are interested in the town of Anniston,
+which is a place according to the Census Bureau,
+so we'll click on the "Places" link.
+
+That link brings up a list of states for which data are available.
+
+.. note:: The Census Bureau is releasing data for each state on a rolling basis starting in mid June. Data for a few states will be released each week until all states are available sometime in August.
+
+We're looking for a place in Alabama, so find the link for Alabama and click it.
+
+You should now see several columns of places in Alabama.
+
+.. note:: The Census Bureau has several suffixes for "places": town, city and CDP. For details on what these mean, please see <tk>.
+
+The list of places is fairly long; you have two options:
+
+1. You can scroll through the list looking for Anniston
+2. You can start typing "anniston" (there's no text field to click on, just start typing). As you type, the list will be filtered by what you've typed so far. By the time you get to "ann," Anniston should be the only item left in the list.
+
+Once you find Anniston, click on the link to view the data.
+
+When the data page first loads, a few Census tables will be shown by default.
+These tables include race, ethnicity, age and housing information.
+Using the table browser on the left, you can show or hide the tables related to your query.
+
+We're looking for race and ethnicity so uncheck all of the tables except for **P5: Hispanic or Latino Origin by Race**.
+
+Now that we are viewing the data for Anniston, let's add data for the county and state to our view so we can compare them.
+
+Start by clicking the "Add another geography to compare" button. A small window will appear with a menu that should look familiar.
+
+This time, we want to look up Calhoun County, Alabama, so click on "Counties" and then "Alabama." When you get to the list of counties in Alabama, either begin typing "Calhoun" to filter the list, or scroll through the list to find it. Then click it.
+
+You will be taken back to the data view page, but now there will be a set of data for Anniston as well as the same set of data for Calhoun County, but we still want to add data for the entire state.
+
+This time, instead of using the "Add another geography" button, we can click on the "<tk>" button to automatically add the state data to our view.
+
+With Anniston, Calhoun County and Alabama state data now in our view, we can compare the racial and ethnic make-ups of the town, county and state.
+
+To download the data for further analysis in Excel or another program, click on the "CSV" button.
+
+Question 2: What part of my town has the lowest median age?
+===========================================================
Oops, something went wrong.

0 comments on commit 14922c8

Please sign in to comment.