You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.rst
+21-72Lines changed: 21 additions & 72 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,100 +5,49 @@ User Documentation
5
5
6
6
The Pharus project is still early in its life and the maintainers are currently actively developing with a priority of addressing first critical issues directly related to the deliveries of `Alpha <https://github.com/datajoint/pharus/milestone/1>`_ and `Beta <https://github.com/datajoint/pharus/milestone/2>`_ milestones. Please be advised that while working through our milestones, we may restructure/refactor the codebase without warning until we issue our `Official Release <https://github.com/datajoint/pharus/milestone/3>`_ currently planned as ``0.1.0`` on ``2021-03-31``.
7
7
8
-
``pharus`` is a generic REST API server backend for DataJoint pipelines built on top of ``flask``, ``datajoint``, and ``pyjwt``.
8
+
``pharus`` is a generic REST API server backend for `DataJoint<https://datajoint.io>`_ pipelines built on top of ``flask``, ``datajoint``, and ``pyjwt``.
- Copy a ``*-docker-compose.yaml`` file corresponding to your usage to ``docker-compose.yaml``. This file is untracked so feel free to modify as necessary. Idea is to commit anything generic but system/setup dependent should go on 'your' version i.e. local UID/GID, etc.
24
-
- Check the first comment which will provide the best instruction on how to start the service; yes, it is a bit long. Note: Any of the keyword arguments prepended to the ``docker-compose`` command can be safely moved into a dedicated ``.env`` and read automatically if they are not evaluated i.e. ``$(...)``. Below is a brief description of the non-evaluated environment variables:
AS_SCRIPT= # If 'TRUE', will not keep container alive but run tests and exit
32
-
33
-
.. note::
34
-
35
-
Deployment options currently being considered are `Docker Compose <https://docs.docker.com/compose/install/>`_ and `Kubernetes <https://kubernetes.io/docs/tutorials/kubernetes-basics/>`_.
36
-
37
-
Run Locally w/ Python
38
-
---------------------
39
-
40
-
- Set environment variables for port assignment (``PHARUS_PORT``, defaults to 5000) and API route prefix (``PHARUS_PREFIX`` e.g. ``/api``, defaults to empty string).
41
-
- For development, use CLI command ``pharus``. This method supports hot-reloading so probably best coupled with ``pip install -e ...``.
42
-
- For production, use ``gunicorn --bind 0.0.0.0:${PHARUS_PORT} pharus.server:app``.
43
-
44
-
Run Tests for Development w/ Pytest and Flake8
45
-
----------------------------------------------
46
-
47
-
- Set ``pharus`` testing environment variables:
48
-
49
-
.. code-block:: bash
50
-
51
-
PKG_DIR=/opt/conda/lib/python3.8/site-packages/pharus # path to pharus installation
52
-
TEST_DB_SERVER=example.com:3306 # testing db server address
53
-
TEST_DB_USER=root # testing db server user (needs DDL privilege)
54
-
TEST_DB_PASS=unsecure # testing db server password
55
-
56
-
- For syntax tests, run ``flake8 ${PKG_DIR} --count --select=E9,F63,F7,F82 --show-source --statistics``
57
-
- For pytest integration tests, run ``pytest -sv --cov-report term-missing --cov=${PKG_DIR} /main/tests``
58
-
- For style tests, run ``flake8 ${PKG_DIR} --count --max-complexity=20 --max-line-length=95 --statistics``
24
+
Prerequisites
25
+
-------------
59
26
60
-
Creating Sphinx Documentation from Scratch
61
-
------------------------------------------
27
+
Download the ``docker-compose-deploy.yaml`` docker environment from the source located `here <https://github.com/datajoint/pharus/releases/latest/download/docker-compose-deploy.yaml>`_.
62
28
63
-
Recommend the follow to be ran within the ``pharus`` container in ``docs`` Docker Compose environment.
29
+
Running the API server
30
+
----------------------
64
31
65
-
- Run the following commands and complete the prompts as requested.
32
+
To start the API server, use the command:
66
33
67
34
.. code-block:: bash
68
35
69
-
mkdir docs
70
-
cd docs
71
-
sphinx-quickstart
72
-
73
-
- In ``docs/conf.py`` add to the beginning:
74
-
75
-
.. code-block:: python
36
+
PHARUS_VERSION=0.1.0b2 docker-compose -f docker-compose-deploy.yaml up -d
76
37
77
-
import os
78
-
import sys
79
-
sys.path.insert(0, os.path.abspath('..'))
80
-
81
-
- In ``docs/conf.py:extensions`` append ``['sphinx.ext.autodoc', 'sphinxcontrib.httpdomain']``. See ``requirements_docs.txt`` and ``docker-compose-docs.yaml`` for details on documentation dependencies.
82
-
- Run the following to automatically generate the API docs:
38
+
To stop the API server, use the command:
83
39
84
40
.. code-block:: bash
85
41
86
-
sphinx-apidoc -o . .. ../tests/* ../setup.py
87
-
88
-
- Add ``modules`` within the ``toctree`` directive in ``index.rst``.
89
-
- Build the docs by running:
90
-
91
-
.. code-block:: bash
92
-
93
-
make html
42
+
PHARUS_VERSION=0.1.0b2 docker-compose -f docker-compose-deploy.yaml down
94
43
95
44
References
96
45
----------
97
46
47
+
- DataJoint
48
+
49
+
- https://datajoint.io
50
+
98
51
- DataJoint LabBook (a companion frontend)
99
52
100
53
- https://github.com/datajoint/datajoint-labbook
101
-
102
-
- Python Tutorial for Flask, Swagger, and Automated docs
- Copy the docker environment (i.e. ``*-docker-compose.yaml``) of your choice corresponding to your usage to ``docker-compose.yaml``. This file is untracked so feel free to modify as necessary. Idea is to commit anything generic but system/setup dependent should go on 'your' version i.e. local UID/GID, etc.
14
+
- Check the first header comment which will provide the best instruction on how to start the service; yes, it is a bit long. Note: Any of the keyword arguments prepended to the ``docker-compose`` command can be safely moved into a dedicated ``.env`` and read automatically if they are not evaluated i.e. ``$(...)``. Below is a brief description of the non-evaluated environment variables:
AS_SCRIPT= # If 'TRUE', will not keep container alive but run tests and exit
22
+
23
+
.. note::
24
+
25
+
Deployment options currently being considered are `Docker Compose <https://docs.docker.com/compose/install/>`_ and `Kubernetes <https://kubernetes.io/docs/tutorials/kubernetes-basics/>`_.
26
+
27
+
Run Locally w/ Python
28
+
---------------------
29
+
30
+
- Set environment variables for port assignment (``PHARUS_PORT``, defaults to 5000) and API route prefix (``PHARUS_PREFIX`` e.g. ``/api``, defaults to empty string).
31
+
- For development, use CLI command ``pharus``. This method supports hot-reloading so probably best coupled with ``pip install -e ...``.
32
+
- For production, use ``gunicorn --bind 0.0.0.0:${PHARUS_PORT} pharus.server:app``.
33
+
34
+
Run Tests for Development w/ Pytest and Flake8
35
+
----------------------------------------------
36
+
37
+
- Set ``pharus`` testing environment variables:
38
+
39
+
.. code-block:: bash
40
+
41
+
PKG_DIR=/opt/conda/lib/python3.8/site-packages/pharus # path to pharus installation
42
+
TEST_DB_SERVER=example.com:3306 # testing db server address
43
+
TEST_DB_USER=root # testing db server user (needs DDL privilege)
44
+
TEST_DB_PASS=unsecure # testing db server password
45
+
46
+
- For syntax tests, run ``flake8 ${PKG_DIR} --count --select=E9,F63,F7,F82 --show-source --statistics``
47
+
- For pytest integration tests, run ``pytest -sv --cov-report term-missing --cov=${PKG_DIR} /main/tests``
48
+
- For style tests, run ``flake8 ${PKG_DIR} --count --max-complexity=20 --max-line-length=95 --statistics``
49
+
50
+
Creating Sphinx Documentation from Scratch
51
+
------------------------------------------
52
+
53
+
Recommend the follow to be ran within the ``pharus`` container in ``docs`` Docker Compose environment.
54
+
55
+
- Run the following commands and complete the prompts as requested.
56
+
57
+
.. code-block:: bash
58
+
59
+
mkdir docs
60
+
cd docs
61
+
sphinx-quickstart
62
+
63
+
- In ``docs/conf.py`` add to the beginning:
64
+
65
+
.. code-block:: python
66
+
67
+
import os
68
+
import sys
69
+
sys.path.insert(0, os.path.abspath('..'))
70
+
71
+
- In ``docs/conf.py:extensions`` append ``['sphinx.ext.autodoc', 'sphinxcontrib.httpdomain']``. See ``requirements_docs.txt`` and ``docker-compose-docs.yaml`` for details on documentation dependencies.
72
+
- Run the following to automatically generate the API docs:
73
+
74
+
.. code-block:: bash
75
+
76
+
sphinx-apidoc -o . .. ../tests/* ../setup.py
77
+
78
+
- Add ``modules`` within the ``toctree`` directive in ``index.rst``.
79
+
- Build the docs by running:
80
+
81
+
.. code-block:: bash
82
+
83
+
make html
84
+
85
+
References
86
+
----------
87
+
88
+
- DataJoint
89
+
90
+
- https://datajoint.io
91
+
92
+
- DataJoint LabBook (a companion frontend)
93
+
94
+
- https://github.com/datajoint/datajoint-labbook
95
+
96
+
- Python Tutorial for Flask, Swagger, and Automated docs
0 commit comments