WIP: Contrib guide update (#845)

Rewrite docs tech guide

.gitignore

@@ -21,9 +21,10 @@ tmp*
 style-checks.py
 extra.py
 
-# Testing
+# testing
 .hypothesis/
 .pytest_cache/
 
 # IDE files
-.idea/
+.idea/
+.vscode/

odk1-src/conf.py

@@ -281,6 +281,9 @@ def setup(app):
 .. role:: arg
     :class: arg
 """
+# if you add lines to rst_prolog, 
+# please update the note about warnings offsets
+# in shared-src/docs-tech-guide.rst
 
 # At bottom of every document
 download_pdf = """

requirements.txt

@@ -18,7 +18,7 @@ MarkupSafe==1.0
 more-itertools==4.3.0
 olefile==0.46
 pathtools==0.1.2
-Pillow==4.3.0
+Pillow>=4.3.0
 pluggy==0.7.1
 port-for==0.3.1
 proselint==0.10.2
@@ -32,12 +32,12 @@ requests==2.14.2
 six==1.10.0
 smmap2==2.0.4
 snowballstemmer==1.2.1
-Sphinx==1.6.6
 sphinx-autobuild==0.7.1
 sphinx-rtd-theme==0.4.1
 sphinx-tabs==1.1.7
+Sphinx==1.6.6
 sphinxcontrib-spelling==4.2.0
 sphinxcontrib-websupport==1.0.1
 tornado==5.1.1
 typing==3.6.1
-watchdog==0.9.0
+watchdog==0.9.0

shared-src/_static/js/custom.js

@@ -1,3 +1,4 @@
+// This JS file is in shared-src.
 // Implement Details-like hide/show on class "details"
 
 $(function(){

shared-src/docs-developer-guide.rst

@@ -340,3 +340,19 @@ To exclude an built-in proselint check,
 specify the check name in the check list
 in the function :py:func:`exclude_checks`
 in the file :file:`style-test.py`.
+
+
+
+
+
+
+
+.. 
+  If you are working on 
+  the design, testing, or deployment of the docs, 
+  you might need to install an additional PyPi package. 
+  If so, 
+  please update the :file:`requirements.txt` file with 
+  :command:`pip freeze > requirements.txt`. 
+  Pull requests which change :file:`requirements.txt` 
+  should include a note about why the new package is needed.

shared-src/docs-extras.rst.scratch

@@ -0,0 +1,52 @@
+   Ideally, each issue represents a single small project
+   to fix one well-defined problem with the documentation.
+   Examples of well-defined single issues include:
+
+   - Write a section to the form questions document describing new type of question
+   - Fix the formatting in the contributor's guide
+   - Redirect old page URI to new
+   - Add style testing for ODK2 branding
+   - Change the display font
+
+   As these examples show, documentation projects include:
+
+   - writing new documentation
+   - editing existing documentation
+   - coding related to the design of the documentation website
+   - coding related to how the documentation is built, tested, and published
+
+   This means that, whatever your skill or interest,
+   there is probably an issue you can work on.
+
+   Sometimes, issues are not well defined yet.
+   This might be because we only have a vague idea of a need,
+   or because we're not yet sure how to solve a problem,
+   or because no one has had the time to write down the details.
+   As you are getting started, 
+   try to focus on issues that have a clear goal.
+   Once you have some experience with the documentation,
+   you can start to help clarify issues so we can move forward on them.
+
+
+
+
+
+
+.. note::
+
+   If you rename a document file (:file:`*.rst`), 
+   be sure that you add the redirect in your PR.
+
+   To add the redirect, go to :file:`s3_website.yml`, 
+   and add a mapping from the old file name to the new file name 
+   below the **redirects:** line, one mapping per line. 
+
+   If you have renamed :file:`old-name.rst` to :file:`new-name.rst`:
+
+   .. code-block:: yaml
+
+     redirects:
+      old-name/index.html: new-name
+
+   Notice the inclusion of ``/index.html`` on the left side.
+

shared-src/docs-style-guide.rst

@@ -1,5 +1,5 @@
 *****************
-Style Guide
+Docs Style Guide
 *****************
 
 .. _spelling-and-grammar: