Merge pull request #68 from edx/robrap/ARCHBOM-1721-how-to-annotate-settings

ARCHBOM-1721: docs: add how-to docs for settings and new annotations

Author: robrap

docs/conf.py

@@ -470,6 +470,7 @@ def get_version(*file_paths):
     'python': ('https://docs.python.org/3.6', None),
     'django': ('https://docs.djangoproject.com/en/1.11/', 'https://docs.djangoproject.com/en/1.11/_objects/'),
     'model_utils': ('https://django-model-utils.readthedocs.io/en/latest/', None),
+    'edx_toggles': ('https://edx.readthedocs.io/projects/edx-toggles/en/latest/', None),
 }
 
 

docs/contrib/how_to/add_new_annotations_and_extracted_docs.rst

@@ -0,0 +1,33 @@
+**********************************************
+How to: Add new annotations and extracted docs
+**********************************************
+
+.. contents::
+   :depth: 1
+   :local:
+
+Example annotations and automated docs
+======================================
+
+Annotations are a great way to keep documentation close to the code, but also be able to extract into documentation to be published on Readthedocs.
+
+As an example, we have added `feature toggle annotations to the edx-platform codebase`_. A `Readthedocs document with the edx-platform feature toggles`_ has been generated from them.
+
+.. _feature toggle annotations to the edx-platform codebase: https://github.com/edx/edx-platform/search?q=toggle_name
+.. _Readthedocs document with the edx-platform feature toggles: https://edx.readthedocs.io/projects/edx-platform-technical/en/latest/featuretoggles.html
+
+Add your own annotations and docs
+=================================
+
+The following steps need to be performed to document new types of annotations in edx-platform. Adapt the final steps as appropriate for other services.
+
+* Define a `new annotation format in code_annotations/contrib/config`_. See the feature toggle annotations as an example.
+* Create a `Sphinx extension to collect these annotations`_. You can base it on the featuretoggles and settings extensions.
+* Read and update :doc:`../sphinx_extensions`.
+* Add a new documentation page in the `edx-platform technical docs that will use this Sphinx extension`_.  Adapt this step as needed for other services.
+* As required, add `custom linting for the new annotations to edx-lint`_. Again, follow the toggle and setting checkers as examples.
+
+.. _new annotation format in code_annotations/contrib/config: https://github.com/edx/code-annotations/tree/master/code_annotations/contrib/config
+.. _Sphinx extension to collect these annotations: https://github.com/edx/code-annotations/tree/master/code_annotations/contrib/sphinx/extensions
+.. _edx-platform technical docs that will use this Sphinx extension: https://github.com/edx/edx-platform/tree/master/docs/technical
+.. _custom linting for the new annotations to edx-lint: https://github.com/edx/edx-lint/blob/master/edx_lint/pylint/annotations_check.py

docs/contrib/how_to/documenting_django_settings.rst

@@ -0,0 +1,64 @@
+***********************************
+How to: Documenting Django settings
+***********************************
+
+.. contents::
+   :depth: 1
+   :local:
+
+Types of Django Settings
+========================
+
+For documentation purposes, in the Open edX codebase there are two types of Django settings:
+
+* Non-boolean Django settings.
+* Boolean Django settings, also known as feature toggles.
+
+This how-to is concerned with the non-boolean Django settings. For boolean Django settings, or feature toggles, read :doc:`how-to document feature toggles <edx_toggles:how_to/documenting_new_feature_toggles>` instead.
+
+The documentation of Django settings is a crucial source of information for a very wide audience, including Open edX operators, product owners and developers. The documentation will be available to developers directly in code, and extracted into a human-readable document to be used by all audiences, and especially for Open edX operators.
+
+Please keep all of these audiences in mind when crafting your documentation.
+
+Example Documentation
+=====================
+
+Boilerplate template
+--------------------
+
+Copy-paste this boilerplate template to document a Django setting::
+
+    # .. setting_name: SOME_SETTING_NAME
+    # .. setting_default: Replace this with the default (non-boolean) value of the setting.
+    # .. setting_description: Add here a detailed description of the purpose and usage of this setting.
+    #   Note that all annotations can be spread over multiple lines by prefixing every line after the first by
+    #   at least three spaces (two spaces plus the leading space).
+    # .. setting_warning: (Optional) Add here additional instructions that users should be aware of. For instance, dependency
+    #   on additional settings or feature toggles should be referenced here. If this field is not needed, simply remove it.
+    SOME_SETTING_NAME = ...
+
+If you have a dict of settings, you can use the following example::
+
+    # .. setting_name: SOME_SETTING_DICT_NAME
+    # .. setting_default: dict of settings
+    # .. setting_description: First provide a general description about all the settings in the dict. Then include a sentence like:
+    #   See SOME_SETTING_DICT_NAME[XXX] documentation for details of each setting.
+    SOME_SETTING_DICT_NAME = dict(
+
+        # .. setting_name: SOME_SETTING_DICT_NAME['SOME_SETTING_NAME']
+        # ...  # See docs above for the other setting annotations.
+        SOME_SETTING_NAME = ...,
+
+    )
+
+Additional details
+==================
+
+There are a variety of tips in `certain sections of the how-to for documenting feature toggles`_, that are applicable to documenting non-boolean Django settings as well, but are not duplicated in this document. We recommend you get familiar with the applicable subsections of "Additional details" and "Documenting legacy feature toggles" from the feature toggle how-to.
+
+.. _certain sections of the how-to for documenting feature toggles: https://edx.readthedocs.io/projects/edx-toggles/en/latest/how_to/documenting_new_feature_toggles.html#additional-details
+
+Additional resources
+====================
+
+The documentation format used to annotate non-boolean Django settings is also available from code-annotations repository: `setting_annotations.yaml <https://github.com/edx/code-annotations/blob/master/code_annotations/contrib/config/setting_annotations.yaml>`__.

docs/sphinx_extensions.rst docs/contrib/sphinx_extensions.rstdocs/sphinx_extensions.rst renamed to docs/contrib/sphinx_extensions.rst

@@ -11,19 +11,27 @@ Contents:
 
 .. toctree::
    :maxdepth: 2
+   :caption: General
 
-   readme
+   README <readme>
    getting_started
    writing_annotations
    static_search
    django_search
    configuration
-   sphinx_extensions
    extensions
    testing
-   modules
+   Package Reference <modules>
    changelog
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Contrib Code
+
+   decisions/0001-config-and-tools
+   contrib/how_to/add_new_annotations_and_extracted_docs
+   contrib/sphinx_extensions
+   contrib/how_to/documenting_django_settings
 
 Indices and tables
 ==================