Merge pull request #40 from cmu-delphi/issue-#27-Document-the-API

Issue #27 document the api

Author: BrainIsDead

Pipfile

@@ -15,7 +15,6 @@ django-health-check = "*"
 django-cors-headers = "*"
 django-debug-toolbar = "*"
 gunicorn = "*"
-pygraphviz = "*"
 django-bootstrap-v5 = "*"
 factory-boy = "*"
 linkpreview = "*"
@@ -28,6 +27,11 @@ django-extensions-models = "*"
 mypy = "*"
 django-stubs = "*"
 tzdata = "*"
+pyparsing = "*"
+pydot = "*"
+django-docs = "*"
+sphinxcontrib-django = "*"
+sphinx-rtd-theme = "*"
 
 [dev-packages]
 flake8 = "*"

Pipfile.lock

@@ -101,6 +101,10 @@ Changes of this sort should be carefully evaluated as they may require interacti
 ## [Django admin](https://docs.djangoproject.com/en/4.1/ref/contrib/admin/) web interface (user should be `is_staff` or `is_superuser`)
 `http://localhost:8000/admin`
 
+## Read the docs (Sphynx)
+`http://localhost:8000/<MAIN_PAGE>/docs/index.html`
+
+
 
 ## Import data from admin interface
 
@@ -133,20 +137,20 @@ To import data from a CSV file must meet the requirements:
 * Colums should be saparateb by `","`
 
 Othervice you will receive Errors during import process:
-![Import errors](./docs/image-3.png)
+![Import errors](./src/docs/source/_static/import_errors.png)
 
 
 1. Import `SourceSubdivision` instances with `SourceSubdivisionResource` - [http://localhost:8000/admin/datasources/sourcesubdivision/import/](http://localhost:8000/admin/datasources/sourcesubdivision/import/)
-![Import `SourceSubdivision` instances](./docs/image.png)
-![Confirm importing `SourceSubdivision` instances](./docs/image-1.png)
+![Import `SourceSubdivision` instances](./src/docs/source/_static/import_source_subdivision.png)
+![Confirm importing `SourceSubdivision` instances](./src/docs/source/_static/import_confirm_source_subdivision.png)
 
 2. Import `Signal` instances with `SignalResource` - [http://localhost:8000/admin/signals/signal/import/](http://localhost:8000/admin/signals/signal/import/)
-![Import `Signal` instances](./docs/image-2.png)
-![Confirm importing `Signal` instances](./docs/image-4.png)
+![Import `Signal` instances](./src/docs/source/_static/import_signals.png)
+![Confirm importing `Signal` instances](./src/docs/source/_static/import_confirm_signals.png)
 
 3. Import `Signal.base` fields with `SignalBaseResource` - [http://localhost:8000/admin/signals/signal/import/](http://localhost:8000/admin/signals/signal/import/)
-![Import `Signal.base` field](./docs/image-5.png)
-![Confirm importing `Signal.base` fields](./docs/image-6.png)
+![Import `Signal.base` field](./src/docs/source/_static/import_signals_base.png)
+![Confirm importing `Signal.base` fields](./src/docs/source/_static/import_confirm_signals_base.png)
 
 ## Deployment
 

README.md

@@ -0,0 +1 @@
+.git

git

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

src/docs/Makefile

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 03f0c893b0f96210097f7e139de537c3
+tags: 645f666f9bcd5a90fca523b33c5a78b7

src/docs/build/doctrees/base.doctree

@@ -0,0 +1,29 @@
+base.migrations package
+=======================
+
+Submodules
+----------
+
+base.migrations.0001\_initial module
+------------------------------------
+
+.. automodule:: base.migrations.0001_initial
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+base.migrations.0002\_link\_created\_link\_modified module
+----------------------------------------------------------
+
+.. automodule:: base.migrations.0002_link_created_link_modified
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: base.migrations
+   :members:
+   :undoc-members:
+   :show-inheritance:

src/docs/build/doctrees/base.migrations.doctree

@@ -0,0 +1,54 @@
+base package
+============
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   base.migrations
+   base.tests
+
+Submodules
+----------
+
+base.admin module
+-----------------
+
+.. automodule:: base.admin
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+base.apps module
+----------------
+
+.. automodule:: base.apps
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+base.models module
+------------------
+
+.. automodule:: base.models
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+base.views module
+-----------------
+
+.. automodule:: base.views
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: base
+   :members:
+   :undoc-members:
+   :show-inheritance:

src/docs/build/doctrees/base.tests.doctree

@@ -0,0 +1,29 @@
+base.tests package
+==================
+
+Submodules
+----------
+
+base.tests.factories module
+---------------------------
+
+.. automodule:: base.tests.factories
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+base.tests.test\_models module
+------------------------------
+
+.. automodule:: base.tests.test_models
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: base.tests
+   :members:
+   :undoc-members:
+   :show-inheritance:

src/docs/build/doctrees/data_import.doctree

@@ -0,0 +1,91 @@
+Import data from admin interface
+================================
+
+For data import used
+`django-import-export <https://django-import-export.readthedocs.io/en/latest/index.html>`__
+library
+
+The code consists of Django resource classes that are used for importing
+and exporting CSV files using the Django Import-Export library:
+
+Resources
+---------
+
+1. ``SignalResource`` - this resource class is used for importing ``Signal`` models:
+
+   - Defines various fields such as ``name``, ``display_name``, ``pathogen``, ``signal_type``, and ``source``.
+   - Defines the ``before_import_row`` method, which is called before importing each row and allows for pre-processing of the data.
+   - Includes methods like ``is_url_in_domain`` to check if a URL belongs to a specific domain, ``fix_boolean_fields`` to handle boolean fields, and ``process_links`` to process the links field.
+
+2. ``SignalBaseResource`` - This resource class is used for updating
+   already created ``Signal`` models ``base`` fields with base Signals:
+
+   -  Defines various fields such as ``name``, ``display_name``,
+      ``base``, and ``source``.
+   -  Defines the ``before_import_row`` method, which is called before
+      importing each row and allows for pre-processing of the data.
+   -  The ``process_base`` method is responsible for processing the
+      ``base`` field by retrieving the corresponding ``Signal`` object
+      based on the provided ``name`` and ``source``.
+
+3. ``SourceSubdivisionResource`` - this resource class is used for
+   importing ``SourceSubdivision`` models:
+
+   -  It defines fields such as ``name``, ``display_name``,
+      ``description``, ``data_source``, and ``links``.
+   -  It includes the ``before_import_row`` method for pre-processing
+      each row before importing.
+   -  The ``process_links`` method is responsible for processing the
+      ``links`` field by creating ``Link`` objects based on the provided
+      URLs.
+   -  The ``process_datasource`` method processes the ``data_source``
+      field by creating or retrieving a ``DataSource`` object based on
+      the provided name.
+
+These resource classes provide a structured way to import CSV files.
+They define the fields, handle pre-processing of data, and interact with
+the corresponding models and related objects.
+
+Import data flow
+----------------
+
+CSV preparation
+~~~~~~~~~~~~~~~
+
+To import data from a CSV file must meet the requirements:
+   - CSV file should be properly formatted and contains all the required fields for
+     importing, as specified by the resource classes (``SignalResource``, ``SignalBaseResource``, ``SourceSubdivisionResource``).
+   - The header rowof the CSV file should match the field names defined in the resource classes.
+   - It should not contain empty rows (empty rows may cause validation errors during the import)
+   - Colums should be saparateb by ``","``
+
+Othervice you will receive Errors during import process:
+
+|Import errors|
+
+Data import
+~~~~~~~~~~~
+
+1. Import ``SourceSubdivision`` instances with
+   ``SourceSubdivisionResource`` -
+   http://localhost:8000/admin/datasources/sourcesubdivision/import/
+   |Import ``SourceSubdivision`` instances| |Confirm importing
+   ``SourceSubdivision`` instances|
+
+
+2. Import ``Signal`` instances with ``SignalResource`` -
+   http://localhost:8000/admin/signals/signal/import/ |Import ``Signal``
+   instances| |Confirm importing ``Signal`` instances|
+
+
+3. Import ``Signal.base`` fields with ``SignalBaseResource`` -
+   http://localhost:8000/admin/signals/signal/import/ |Import
+   ``Signal.base`` field| |Confirm importing ``Signal.base`` fields|
+
+.. |Import errors| image:: ./_static/import_errors.png
+.. |Import ``SourceSubdivision`` instances| image:: ./_static/import_source_subdivision.png
+.. |Confirm importing ``SourceSubdivision`` instances| image:: ./_static/import_confirm_source_subdivision.png
+.. |Import ``Signal`` instances| image:: ./_static/import_signals.png
+.. |Confirm importing ``Signal`` instances| image:: ./_static/import_confirm_signals.png
+.. |Import ``Signal.base`` field| image:: ./_static/import_signals_base.png
+.. |Confirm importing ``Signal.base`` fields| image:: ./_static/import_confirm_signals_base.png

src/docs/build/doctrees/datasources.doctree

@@ -0,0 +1,37 @@
+datasources.migrations package
+==============================
+
+Submodules
+----------
+
+datasources.migrations.0001\_initial module
+-------------------------------------------
+
+.. automodule:: datasources.migrations.0001_initial
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+datasources.migrations.0002\_alter\_sourcesubdivision\_db\_source module
+------------------------------------------------------------------------
+
+.. automodule:: datasources.migrations.0002_alter_sourcesubdivision_db_source
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+datasources.migrations.0003\_datasource\_created\_datasource\_modified\_and\_more module
+----------------------------------------------------------------------------------------
+
+.. automodule:: datasources.migrations.0003_datasource_created_datasource_modified_and_more
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: datasources.migrations
+   :members:
+   :undoc-members:
+   :show-inheritance:

src/docs/build/doctrees/datasources.migrations.doctree

@@ -0,0 +1,62 @@
+datasources package
+===================
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   datasources.migrations
+   datasources.tests
+
+Submodules
+----------
+
+datasources.admin module
+------------------------
+
+.. automodule:: datasources.admin
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+datasources.apps module
+-----------------------
+
+.. automodule:: datasources.apps
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+datasources.models module
+-------------------------
+
+.. automodule:: datasources.models
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+datasources.resources module
+----------------------------
+
+.. automodule:: datasources.resources
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+datasources.views module
+------------------------
+
+.. automodule:: datasources.views
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: datasources
+   :members:
+   :undoc-members:
+   :show-inheritance: