Merge pull request #264 from guzman-raphael/release013-compatibility

Update docs compatible with release djpy 0.13

Author: dimitri-yatsenko

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 Observes [Semantic Versioning](https://semver.org/spec/v2.0.0.html) standard and [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) convention.
 
+## [0.2.0] - 2021-03-24
+### Added
+- Add `update1` documentation and reference it properly to datajoint-python, release 0.13. PR #264
+- Add `query_caching` documentation and reference it properly to datajoint-python, release 0.13. PR #264
+- Add transpiler design documentation and reference it properly to datajoint-python, release 0.13. PR #264
+
+### Changed
+- Modify the markdown parsing to `m2r2` and allow content to be included. PR #264
+- Update reverse proxy image from `datajoint` org. PR #264
+
 ## [0.1.5] - 2021-03-11
 ### Added
 - Numbering for easy reference in `Contribute` section. PR #262
@@ -37,6 +47,7 @@ Observes [Semantic Versioning](https://semver.org/spec/v2.0.0.html) standard and
 - `local-docker-compose.yml` environment. PR #257
 - `entrypoint.sh` which is now unnecessary for the image. PR #257
 
+[0.2.0]: https://github.com/datajoint/datajoint-docs/compare/v0.1.5...v0.2.0
 [0.1.5]: https://github.com/datajoint/datajoint-docs/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/datajoint/datajoint-docs/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/datajoint/datajoint-docs/releases/tag/v0.1.3

build_versions.json

@@ -1,5 +1,6 @@
 {
   "python": [
+              "v0.13",
               "v0.12",
               "v0.11"
             ],

contents/conf.py

@@ -22,7 +22,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.mathjax','sphinx.ext.imgconverter']
+extensions = ['sphinx.ext.mathjax','sphinx.ext.imgconverter', 'm2r2']
 
 # Add any paths that contain templates here, relative to this directory.
 
@@ -52,7 +52,7 @@
 # The short X.Y version.
 version = ''
 # The full version, including alpha/beta/rc tags.
-release = '0.1.5'
+release = '0.2.0'
 
 
 # The language for content autogenerated by Sphinx. Refer to documentation
@@ -65,7 +65,8 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['README.md', '_build', 'Thumbs.db', '.DS_Store', '*/*_lang[0-9].rst', '*/*_WIP.rst']
+exclude_patterns = ['README.md', '_build', 'Thumbs.db', '.DS_Store', '*/*_lang[0-9].rst',
+                    '*/*_lang[0-9].md', '*/*_WIP.rst']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'default'

contents/manipulation/3-Cautious-Update.rst

@@ -9,9 +9,23 @@ In database programming, the **update** operation refers to modifying the values
 Such an in-place update mechanism is not part of DataJoint's data manipulation model, because it circumvents data :ref:`dependency constraints <referential-integrity>`.
 
 This is not to say that data cannot be changed once they are part of a pipeline.
-In DataJoint, data are changed by replacing entire entities rather than by updating the values of their attributes.
+In DataJoint, data is changed by replacing entire entities rather than by updating the values of their attributes.
 The process of deleting existing entities and inserting new entities with corrected values ensures the :ref:`integrity <integrity>` of the data throughout the pipeline.
 
 This approach applies specifically to automated tables (see :ref:`auto`).
 However, manual tables are often edited outside DataJoint through other interfaces.
 It is up to the user's discretion to allow updates in manual tables, and the user must be cognizant of the fact that updates will not trigger re-computation of dependent data.
+
+Usage
+-----
+
+For some cases, it becomes necessary to deliberately correct existing values where a user has chosen to accept the above responsibility despite the caution.
+
+The ``update1`` method accomplishes this if the record already exists. Note that updates to primary key values are not allowed.
+
+The method should only be used to fix problems, and not as part of a regular workflow. When updating an entry, make sure that any information stored in dependent tables that depends on the update values is properly updated as well.
+
+Examples
+--------
+
+.. include:: 1-Update_lang1.rst

contents/queries/12-Query-Caching.rst

@@ -0,0 +1,24 @@
+.. progress: 10.0 100% Raphael
+
+.. _query-caching:
+
+Query Caching
+=============
+
+Query caching allows avoiding repeated queries to the database by caching the results locally for faster retrieval.
+
+To enable queries, set the query cache local path in ``dj.config``, create the directory, and activate the query caching.
+
+.. include:: 12-Query-Caching_lang1.rst
+
+The ``query_cache`` argument is an aribtrary string serving to differentiate cache states; setting a new value will effectively start a new cache, triggering retrieval of new values once.
+
+To turn off query caching, use
+
+.. include:: 12-Query-Caching_lang2.rst
+
+While query caching is enabled, any insert or delete calls and any transactions are disabled and will raise an error. This ensures that stale data are not used for updating the database in violation of data integrity.
+
+To clear and remove the query cache, use
+
+.. include:: 12-Query-Caching_lang3.rst

contents/queries/13-Transpiler-Design.rst

@@ -0,0 +1,10 @@
+.. progress: 10.0 100% Raphael
+
+.. _transpiler-design:
+
+Transpiler Design
+=================
+
+This section contains the information and reasoning that went into the design of the DataJoint-to-SQL transpiler.
+
+.. mdinclude:: 13-Transpiler-Design_lang1.md

docker-compose-dev.yaml

@@ -32,7 +32,7 @@ services:
         python3 -m http.server
   fakeservices.datajoint.io:
     <<: *net
-    image: raphaelguzman/nginx:v0.0.15
+    image: datajoint/nginx:v0.0.16
     environment:
       - ADD_pharus_TYPE=REST
       - ADD_pharus_ENDPOINT=datajoint-docs:8000

requirements.txt

@@ -2,6 +2,6 @@ sphinx==3.3.1 # search breaks with later versions
 sphinx_rtd_theme
 numpy
 matplotlib
-recommonmark
+m2r2
 #RunNotebook
 #sphinx_bootstrap_theme