[CIVIS-9155] ENH support setting a Civis file's new description att…

…ribute (#498)

* REF be explicit about public functions under civis.io.*

* ENH support 'description' attr in file-creating I/O functions

* TST file 'description' attribute

* DOC explain sphinx doc building

* MAINT update changelog

* MAINT add docs/build/ to .gitignore

.gitignore

@@ -41,9 +41,10 @@ swagger.json
 # Sphinx docs
 docs/source/generated/
 docs/source/api_*.rst
+docs/build/
 
 # IDEs
 .idea
 
 .DS_Store
-.vscode
+.vscode

CHANGELOG.md

@@ -11,6 +11,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
   a `tenacity.Retrying` instance can be provided to customize retries. (#495)
 - Added `civis.workflows.validate_workflow_yaml`
   to validate a Civis Platform workflow YAML definition. (#497)
+- The helper I/O functions that create a Civis file
+  (i.e., `civis.io.file_to_civis`, `civis.io.dataframe_to_file`, and `civis.io.json_to_file`)
+  accept a new `description` keyword argument for the new `description` attribute
+  of Civis file objects. (#498)
 
 ### Changed
 ### Deprecated

README.rst

@@ -162,18 +162,43 @@ See the `documentation <https://civis-python.readthedocs.io>`_ for a more
 complete user guide.
 
 
-Build Documentation Locally
----------------------------
+Building Documentation
+----------------------
+
+Background:
+
+* We use the Sphinx framework. The documentation source files are in ``docs/source/``.
+* All auto-generated files, including the HTML pages, are explicitly not versioned
+  (see ``.gitignore``).
+
+For the public documentation at https://civis-python.readthedocs.io:
+
+* The doc build is configured by ``.readthedocs.yaml``.
+  Normally, even when we need to update the documentation or make a new release of civis-python,
+  neither this configuration YAML file nor Civis's account on the Read the Docs site need
+  any updates.
+* To update the documentation, the files under ``docs/source/`` can be updated as needed.
+  If the "API Resources" page needs to be updated because the upstream Civis API has been updated,
+  then the following need to happen:
+  (i) the new Civis API updates must be accessible by a "standard" Civis Platform user,
+  i.e., not behind a feature flag, and
+  (ii) you'll need to locally run ``python tools/update_civis_api_spec.py`` to update
+  ``civis_api_spec.json`` inside the ``civis`` Python package codebase.
+  It is this JSON file that's the basis for the Civis API information on the "API Resources" page.
+  Regardless of which Civis API key you use to run ``python tools/update_civis_api_spec.py``,
+  the updated ``civis_api_spec.json`` only contains Civis API information available to
+  a standard Civis Platform user.
+
+To build the documentation locally, for testing and development:
+
+* Install the full doc-related dependencies: ``pip install -r docs/requirements.txt``.
+* Run ``sphinx-build -b html docs/source docs/build/html``.
+  In case you would like for the "API Resources" page to locally show what a specific
+  Civis Platform user would see from the Civis API
+  (rather than use the available ``civis_api_spec.json`` for a standard Civis Platform user),
+  set the environment variable ``CIVIS_API_KEY`` to this user's key
+  and prepend this command with ``FETCH_REMOTE_RESOURCES=true``.
 
-To install dependencies for building the documentation::
-
-    pip install -r docs/requirements.txt
-
-To build the API documentation locally::
-
-    sphinx-build -b html docs/source docs/build/html  # or prepend this command with `FETCH_REMOTE_RESOURCES=true ` for the API resources available to the given CIVIS_API_KEY
-
-Then open ``docs/build/html/index.html``.
 
 Command-line Interface (CLI)
 ----------------------------