added and made more consistent docstrings, wrote script that makes minor edits to Sphinx apidocs to improve documentation clarity

docs/Makefile

@@ -14,6 +14,8 @@ MODULEPATH    = ../cisticola
 SOURCEFILES   = cisticola.*
 MODULEFILE    = modules.rst
 
+POST_APIDOC   = edit_apidoc.sh
+
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
@@ -25,6 +27,8 @@ apidoc:
 	rm $(SOURCEDIR)/$(SOURCEFILES)
 	$(SPHINXAPIDOC) $(APIDOCFLAGS) -o "$(SOURCEDIR)" "$(MODULEPATH)"
 	rm $(SOURCEDIR)/$(MODULEFILE)
+	bash $(POST_APIDOC)
+	
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

docs/edit_apidoc.sh

@@ -0,0 +1,17 @@
+# This script makes minor changes to the *.rst files created by Sphinx apidoc
+
+RST_SOURCE_DIR=source
+HIDE_COOKIESTRING="   :exclude-members: cookiestring"
+REPLACE_MAXDEPTH="s/   :maxdepth: 4/   :maxdepth: 1/g"
+
+# Remove display of ``cookiestring`` class variable, otherwise Sphinx generates docs containing the value of your cookiestring, based on your ``YOUTUBE_COOKIESTRING`` environment variable
+for file in cisticola.scraper.base.rst cisticola.scraper.rumble.rst cisticola.scraper.youtube.rst
+do
+    echo "$HIDE_COOKIESTRING" >> $RST_SOURCE_DIR/$file;
+done
+
+# Set max depth to 1 for subpackages (only showing module files), makes it less confusing
+for file in cisticola.rst cisticola.scraper.rst cisticola.transformer.rst
+do
+    sed -i "${REPLACE_MAXDEPTH}" ${RST_SOURCE_DIR}/${file};
+done

docs/source/about.rst

@@ -20,4 +20,9 @@ Cisticola has many components
 
 The data extracted by scrapers varies by platform, but typically includes media files attached to posts. 
 
-Separating the "scraping" and "transforming" steps is useful because it ensures that no data is thrown away during the transormation. There may be some fields in the raw data that aren't included in the transformed format, but could be found to be useful in the future.
+Separating the "scraping" and "transforming" steps is useful because it ensures that no data is thrown away during the transormation. There may be some fields in the raw data that aren't included in the transformed format, but could be found to be useful in the future.
+
+TODO
+- Add diagram
+- Describe common workflow and steps
+- Update environment variables

docs/source/cisticola.rst

@@ -10,7 +10,7 @@ Subpackages
 -----------
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 1
 
    cisticola.scraper
    cisticola.transformer
@@ -19,7 +19,7 @@ Submodules
 ----------
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 1
 
    cisticola.base
    cisticola.utils