Feature/documentation updates and fixes

docs/Options/APIReference.rst

@@ -10,18 +10,18 @@ REST which we are trying to migrate from as well.
 REST Endpoints
 ------------------
 
-Rest API Endpoints can be found here  : https://prod-api.thedeep.io/api-docs/
+`Rest API Endpoints documentation <https://prod-api.thedeep.io/api-docs/>`_
 
 
 GraphQL Endpoints
 --------------------
 
-GraphQL Endpoints points can be found here  : https://prod-api.thedeep.io/graphql-docs/
+`GraphQL Endpoints documentation <https://prod-api.thedeep.io/graphql-docs/>`_
 
 REST API
 ----------
 
-A thorough documentation of the API itself can be found at */api-docs/*.
+A thorough documentation of the API itself can be found at ``/api-docs/``.
 
 **Authentication**
 
@@ -68,7 +68,7 @@ The API can also contain the `next` and `previous` fields indicating the URL to
 Example request:
 
 
-GET /api/v1/leads/?offset=0&limit=1
+``GET /api/v1/leads/?offset=0&limit=1``
 
 Example response:
 
@@ -104,9 +104,7 @@ Example response:
 
 Many APIs also take further query parameters to filter the query set. For example, you can filter Sources by projects using:
 
-.. code-block:: bash
-
-  GET /api/v1/leads/?project=2
+``GET /api/v1/leads/?project=2``
 
 
 The API documentation at */api/v1/docs/* also lists filters available for each API.
@@ -154,4 +152,4 @@ For most types of errors like forbidden, unauthorized and not found, the interna
 
 For server errors, all except the following lists of predefined errors will have internal error code 500 by default.
 
-* 4011 : User is not authenticated. Access token is required in the authorization header.
+* 401 : User is not authenticated. Access token is required in the authorization header.

docs/Options/AwsCopilotDeployment.rst

@@ -74,7 +74,7 @@ Setup each services
  * copilot svc init --name export-worker
 
 
-[Secrets](https://aws.github.io/copilot-cli/docs/commands/secret-init/)
+`Secrets <https://aws.github.io/copilot-cli/docs/commands/secret-init/>`_
 -------------------------------------------------------------------------
 .. code-block:: bash  
 

docs/Options/Changelog.rst

@@ -8,6 +8,6 @@ export secondary data. This repository contains code for DEEP 2.0,
 a large full-stack rewrite of DEEP 1.0.
 
 DEEP's brain is powered by DEEPL, an suite of tools to provide NLP 
-recommendations to the platform. Its code can be found here: https://github.com/the-deep/deepl.
+recommendations to the platform. `Here is its Github repo <https://github.com/the-deep/deepl>`_
 
-More information regarding our chanelog can be found here : https://github.com/the-deep/deeper/wiki
+More information regarding our changelog can be found on the `wiki <https://github.com/the-deep/deeper/wiki>`_

docs/Options/Contributing.rst

@@ -26,7 +26,7 @@ Contributing to the Backend
 
 **Python Coding Guidelines**
 
-- Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/).
+- Follow `PEP 8 <https://www.python.org/dev/peps/pep-0008/>`_.
 
 - Use 4 spaces  . . . . never tabs.
 
@@ -46,8 +46,8 @@ Contributing to the Backend
      ProjectSerializer, ProjectMembershipSerializer
  )
 
-  
-**Write [unit tests](https://docs.djangoproject.com/en/1.11/topics/testing/)**
+
+Write `unit tests <https://docs.djangoproject.com/en/1.11/topics/testing/>`_
 
 FAQ
 ----

docs/Options/Documentation.rst

@@ -0,0 +1,41 @@
+📄 Documentation
+++++++++++++++++
+
+Introduction
+------------
+
+DEEP's documentation is built on top of `Sphinx <https://www.sphinx-doc.org/en/master/>`_ and uses a theme provided by `Read the Docs <https://about.readthedocs.com/?ref=readthedocs.org>`_. We accept contributions to the documentation of the DEEP project too.
+
+Contributions to Documentation
+------------------------------
+
+Contributions to DEEP's documentation must adhere to the contribution guidelines, just like any other code contribution.
+DEEP's documentation is generated as a static page using Sphinx. During deployment, the docs are generated using a pre-deployment pipeline in a similar manner. For local creation of docs, refer the notes below.
+
+**Steps to generate DEEP docs locally**
+
+#. Navigate to the documentation folder:
+
+    .. code-block:: bash  
+
+        cd docs/
+
+#. Install sphinx and supporting packages:
+
+    .. code-block:: bash  
+
+        pip install -r requirements.txt
+
+#. Generate static documentation locally:
+
+    .. code-block:: bash
+
+        make html
+
+#. View the generated docs by opening the index file in your browser, at the following path: :code:`<path-to-project>/docs/_build/html/index.html`
+
+Useful References
+-----------------
+
+*   `sphinx-autobuild <https://pypi.org/project/sphinx-autobuild/>`_ is a tool that auto-builds the documentation everytime a change is detected in the ``docs/`` folder
+*   `rst Cheatsheet <https://bashtage.github.io/sphinx-material/rst-cheatsheet/rst-cheatsheet.html>`_ for a handy reference on reStructuredText, the markup language used by Sphinx

docs/Options/GettingStarted.rst

@@ -21,7 +21,9 @@ docker.
 Clone Deeper Repo
 -------------------
 
-git clone https://github.com/the-deep/deeper.git deep-project-root
+.. code-block:: bash  
+
+  git clone https://github.com/the-deep/deeper.git deep-project-root
 
 **Goto Deeper project root**
 
@@ -31,12 +33,14 @@ git clone https://github.com/the-deep/deeper.git deep-project-root
 
 **Clone client and server**
 
-git clone https://github.com/the-deep/server.git server
+.. code-block:: bash
 
-git clone https://github.com/the-deep/client.git client
-git clone --branch=feature/only-ary https://github.com/the-deep/client.git ./ary-only-client
+  git clone https://github.com/the-deep/server.git server
 
-git clone https://github.com/the-deep/deepl-deep-integration.git deepl-service
+  git clone https://github.com/the-deep/client.git client
+  git clone --branch=feature/only-ary https://github.com/the-deep/client.git ./ary-only-client
+
+  git clone https://github.com/the-deep/deepl-deep-integration.git deepl-service
 
 **Setup client**
 
@@ -46,8 +50,8 @@ git clone https://github.com/the-deep/deepl-deep-integration.git deepl-service
 
 **Building**
 
-Install `docker` and `docker-compose v3`..
-And run the following commands every time dependencies are updated.
+| Install ``docker`` and ``docker-compose v3``
+| Run the following commands every time dependencies are updated.
 
 .. code-block:: bash  
 
@@ -93,8 +97,8 @@ And run the following commands every time dependencies are updated.
 
 **Useful Plugins for Debugging React**
 
-- [React Developer Tools](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi?hl=en)
-- [Redux DevTools](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=en)
+- `React Developer Tools <https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi?hl=en>`_
+- `Redux DevTools <https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=en>`_
 
 **Adding dependencies [web]**
 
@@ -143,7 +147,8 @@ And run the following commands every time dependencies are updated.
 .. code-block:: bash
 
  docker-compose exec web bash
- **Inside web container**
+
+**Inside web container**
 
 .. code-block:: bash
 
@@ -157,7 +162,7 @@ And run the following commands every time dependencies are updated.
 
  docker-compose exec client bash
 
- **Inside client container**
+**Inside client container**
 
 .. code-block:: bash
 

docs/Options/Testing.rst

@@ -87,11 +87,11 @@ from project.models import Project
 
 **References:**
 
-[Writing Django tests](https://docs.djangoproject.com/en/1.11/topics/testing/overview/)
+`Writing Django tests <https://docs.djangoproject.com/en/1.11/topics/testing/overview/>`_
 
-[Writing API tests](http://www.django-rest-framework.org/api-guide/testing/)
+`Writing API tests <http://www.django-rest-framework.org/api-guide/testing/>`_
 
-[Test Mixin](mixin_backend.md)
+`Test Mixin <mixin_backend.md>`_
 
 FrontEnd
 ========
@@ -159,7 +159,7 @@ To test redux-connected components, one can use the `redux-mock-store`:
    });
    });
 
-More examples using redux: [writing tests](https://github.com/reactjs/redux/blob/master/docs/recipes/WritingTests.md).
+More examples using redux: `Writing tests <https://github.com/reactjs/redux/blob/master/docs/recipes/WritingTests.md>`_.
 
 For event based behavioral testing, Enzyme's `simulate` can be used as helper method.
 

docs/conf.py

@@ -25,3 +25,5 @@
 
 html_theme = 'sphinx_rtd_theme'
 html_static_path = ['_static']
+
+pygments_style = 'sphinx'

docs/index.rst

@@ -34,6 +34,7 @@ Development of DEEP began in early 2016 and it is a collaborative project govern
    Options/Testing
    Options/Contributing
    Options/Changelog
-
+   Options/Documentation
+
 
 

docs/requirements.txt

@@ -1,3 +1,3 @@
-sphinx
-sphinx_rtd_theme
-readthedocs-sphinx-search
+Sphinx==7.2.6
+sphinx-rtd-theme==2.0.0
+readthedocs-sphinx-search==0.3.2