Update and fill out documentation #13

bmedx · 2019-01-23T21:00:27Z

Description: Adds documentation for the search tools, cleans up some things which have grown inaccurate.

JIRA: PLAT-2402

doctoryes · 2019-01-23T22:21:23Z

docs/configuration.rst

+
+``coverage_target``
+    A number from 0 - 100 that represents the percentage of Django models in the project that should have annotations.
+    The Django Search tool will fail if run with the ``--coverage`` option if the covered percentage is below this


Nit: ...will fail when run with...

doctoryes · 2019-01-23T22:54:29Z

docs/configuration.rst

-        choice_annotation:
+        ".. annotation_token::":
+        ".. annotation_token2::":
+        "".. choice_annotation::"":


Why does this annotation have double quotes?

No idea, will fix.

doctoryes · 2019-01-23T22:56:29Z

docs/configuration.rst

-      free-form text following the annotation itself. At this time the comment must be all on one line to be included
+    - Basic, or comment, annotations such as ``annotation_token`` and ``first_group_token`` above, allow for
+      free-form text following the annotation itself. Note the colon after the annotation token! In configuration this
+      type is a mapping type, mapping to a null value. At this time the comment must be all on one line to be included


Maybe separate this single-line note into a NOTE: At this time,....?

doctoryes · 2019-01-23T22:59:08Z

docs/django_search.rst

+in some way. If you do not need this functionality and simply want to find annotations and create a report, the static
+search tool is much easier to configure and can search all of your code (instead of just model docstrings).
+
+.. important::


This important should be bolded/capitalized? It seems strange as it is now.

This is a Sphinx admonition. In the processed docs it will highlight the text and put a border around it: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-directives

doctoryes · 2019-01-23T23:00:20Z

docs/django_search.rst

+search tool is much easier to configure and can search all of your code (instead of just model docstrings).
+
+.. important::
+    In order to use the Django tool you must first set the ``DJANGO_SETTINGS_MODULE`` environment variable to point to


Nit: To use the Django tool, you must...

doctoryes · 2019-01-23T23:05:40Z

docs/django_search.rst

+.. code-block:: yaml
+
+    social_django.Association:
+    social_django.Code:


Actually, freshly-created looks like this:

social_django.Association: {} social_django.Code: {}

doctoryes · 2019-01-23T23:07:32Z

docs/django_search.rst

+    second ``.. no_pii::`` annotation to ``social_django.Association``.
+
+.. important::
+    Some types of "local" models are procedurally generated and do not have files in code, for instance those created by


in code, e.g. models created by django-simple-history.

doctoryes · 2019-01-23T23:10:56Z

docs/extensions.rst

 language searches, even the ones that come by default, are implemented as extensions. A language extension is
-responsible for finding all comments in files of the given type.
+responsible for finding all comments in files of the given type. Note that extensions are only used in the Static Search
+and not in Django search, as Django models are obviously all written in Python.


Django Search to mirror Static Search?

doctoryes · 2019-01-23T23:11:18Z

docs/extensions.rst

-``_add_annotation_group`` - On construction this will be called once for each annotation group that is configured,
-    allowing you to do any setup necessary to find these tokens in your search. Note that annotations in a group are
-    *not* also sent to ``_add_annotation_token``, though you can do that yourself.
-


doctoryes · 2019-01-23T23:13:54Z

docs/static_search.rst

+
+Overview
+========
+The Static Search Tool, or Static Tool, is written as an extensible way to find annotations in code. It does this by


The tool performs static...

pwnage101

You already merged, but better late than never! I should have mentioned it was on my TODO list for today.

pwnage101 · 2019-01-24T19:25:43Z

docs/getting_started.rst

-    source_path: ../path/to/be/searched/
+    # Path that you wish to static search, can be passed on the command line
+    # Directories will be searched recursively, but this can also point to a single file
+    source_path: ../


should this example use ./ or ../? Julia once copied this verbatim into the edx-notes-api pii config, and so we had to change it to ./ to only search the local source checkout.

pwnage101 · 2019-01-24T19:29:29Z

docs/writing_annotations.rst

-
-Group members can be be comment or choice types. The only limitation on ordering is that the group member listed first
-in the configuration must also appear first in the comment.
+that all group members are consecutively, though ordering does not matter.


typo: "consecutive"

bmedx added 2 commits January 18, 2019 13:21

Update documentation to match the current state of code

a019760

Add documentation for search tools, more doc cleanup.

a50c178

bmedx requested review from doctoryes, macdiesel and pwnage101 January 23, 2019 21:00

doctoryes reviewed Jan 23, 2019

View reviewed changes

fixup! Add documentation for search tools, more doc cleanup.

dd2172a

doctoryes approved these changes Jan 24, 2019

View reviewed changes

bmedx merged commit b3f1a71 into master Jan 24, 2019

bmedx deleted the bmedx/django_docs branch January 24, 2019 18:51

pwnage101 reviewed Jan 24, 2019

View reviewed changes

Update and fill out documentation #13

Update and fill out documentation #13

Uh oh!

Conversation

bmedx commented Jan 23, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pwnage101 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants