adding links file and skeleton

.github/workflows/deploy-staging.yml

@@ -19,7 +19,6 @@ name: Deploy staging
 on:
   push:
     branches:
-      - main
       - staging
 
 jobs:
@@ -52,7 +51,7 @@ jobs:
           pip install -r requirements.txt
 
       - name: Make HTML
-        run: make html
+        run: make html DOCENV=staging
 
 
       # - name: Modify CNAME file to contain correct directory

README.md

@@ -1,8 +1,19 @@
 # Documentation for RHoMIS 2.0
 
-Skeleton for RHoMIS 2.0 documentation built using sphinx. I thought this would be useful in case we wanted to document our work as we go along. During my last project, I saved all of this documentation until the end and found it made things much more difficult.
+RHoMIS 2.0 documentation built using sphinx.
 
-Install dependencies with `pip install -r requirements.txt`. Make the documentation with the command `make html`. The documentation can then be found in the `_build` directory. To view the documentation in your browser, open the file `_build/html/index.html` in your browser. 
+Install dependencies with `pip install -r requirements.txt`. Make the documentation with the command `make html`. The documentation can then be found in the `_build` directory. To view the documentation in your browser, open the file `_build/html/index.html` in your browser.
+
+The links in this documentation are different for the
+staging and production versions of RHoMIS. If building
+the staging documentation, build the docs with the command:
+
+`make html DOCENV=staging`
+
+If building the production version of the documentation,
+build the docs with the command
+
+`make html DOCENV=production`
 
 Feel free to add to or change any of the documentation. If you would like to add any extra sections, add a file in the `source` directory, then be sure to reference it in the toctree (found in the `index.rst` file). Click [here](https://www.sphinx-doc.org/en/master/contents.html) for further information on using sphinx. The documentation in the `source` folder is written using restructured text. Click [here](https://docutils.sourceforge.io/rst.html) for information on using restructured text.
 

conf.py

@@ -15,6 +15,7 @@
 # sys.path.insert(0, os.path.abspath('.'))
 import sphinx_rtd_theme
 import myst_parser
+import os
 
 # -- Project information -----------------------------------------------------
 
@@ -40,7 +41,8 @@
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store','env/*',
-                    'README.md', 'copy_diagramns.sh']
+                    'README.md', 'copy_diagramns.sh', "source/utils/links-production.rst", 
+                    "source/utils/links-staging.rst"]
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -67,3 +69,29 @@
     '.rst': 'restructuredtext',
     '.md': 'markdown',
 }
+
+
+# make rst_epilog a variable, so you can add other epilog parts to it
+rst_epilog =""
+# Read link all targets from file
+
+docenv = os.getenv("DOCENV")
+if (docenv=="production"):
+    links_file="./source/utils/links-production.rst"
+elif (docenv=="staging"):
+    links_file="./source/utils/links-staging.rst"
+else:
+    raise ValueError("""
+
+    Did not specify whether staging or production environment.
+    Please include DOCENV=staging or DOCENV=production in your
+    command""")
+
+
+print("docenv")
+print(docenv)
+
+with open(links_file) as f:
+     rst_epilog += f.read()
+
+print(rst_epilog)

index.rst

@@ -3,7 +3,10 @@ The Rural Househol Multi-Indicator Survey (RHoMIS)
 
 .. note::
    Want to begin start using RHoMIS, go right to the
-   `RHoMIS App <https://app.l-gorman.com>`_ 
+   `RHoMIS App`_.
+
+.. _app link: https://app.l-gorman.com
+
 
 RHoMIS was designed to improve the process of gathering 
 information from farming households in the rural developing world. 
@@ -22,39 +25,53 @@ The tool is designed to minimise the burden on the rural household,
 to maximise the reliability of responses, and to improve consistency 
 between different studies.
 
-Learn more about RHoMIS :ref:`here <overview>`
+Learn more about what makes RHoMIS :ref:`here <overview>`
 
-.. toctree::
-   :maxdepth: 3
-   :caption: First Steps
+Scientific Background
+###################################
+
+The RHoMIS tool has been built with a high level of scientific rigour. 
+The survey includes proven and widely accepted indicators such as the 
+Food Insecurity Experience Scale (FIES), the Household Dietary Diversity 
+Score (HDDS),  the Hunger and Food Insecurity Access Scale (HFIAS), 
+Food Availabilty (FA), and the Progress out of Poverty Index (PPI). 
+
+Over 15 scientific papers about the tool have either been published or are in 
+the process of being published. You can also view more matierials on `RHoMIS Scientific Output`_
 
-   source/quickstart.rst
-   source/overview.rst
 
 .. toctree::
-   :maxdepth: 3
-   :caption: Designing Surveys
+   :maxdepth: 2
+   :caption: User Guide
 
-   source/survey-builder.rst
+   source/user-guide/first-time-user.rst
+   source/user-guide/building-a-survey.rst
+   source/user-guide/collecting-data.rst
+   source/user-guide/editing-a-survey.rst
+   source/user-guide/processing-data.rst
+   source/user-guide/additional-features.rst
+   source/user-guide/faqs.rst
 
 .. toctree::
-   :maxdepth: 3
-   :caption: Collecting Data
+   :maxdepth: 2
+   :caption: About RHoMIS
 
-   source/data-collection.rst
+   source/about-rhomis/overview.rst
 
 .. toctree::
-   :maxdepth: 3
-   :caption: Processing Data
+   :maxdepth: 2
+   :caption: Contributing to RHoMIS
+
+   source/contributor-guide/contributor-guide.rst
 
-   source/data-processing.rst
 
 .. toctree::
-   :maxdepth: 3
-   :caption: Contrinuting to RhoMIS 2.0
+   :maxdepth: 2
+   :caption: Developer Guide
+
+   source/developer-guide/developer-guide.rst
+   source/developer-guide/survey-builder-dev.rst
+
+
 
-   source/developer-guide.rst
-   source/survey-builder-dev.rst
-   source/analysis-scripts-dev.rst
-   source/data-querying-dashboard-dev.rst
 

requirements.txt

@@ -1,32 +1,99 @@
 alabaster==0.7.12
+appnope==0.1.3
+argon2-cffi==21.3.0
+argon2-cffi-bindings==21.2.0
+asttokens==2.0.5
 attrs==21.2.0
 Babel==2.9.1
+backcall==0.2.0
+beautifulsoup4==4.10.0
+bleach==4.1.0
 certifi==2021.5.30
+cffi==1.15.0
 charset-normalizer==2.0.4
+debugpy==1.6.0
+decorator==5.1.1
+defusedxml==0.7.1
 docutils==0.16
+entrypoints==0.4
+executing==0.8.3
+fastjsonschema==2.15.3
+GDAL==3.4.2
 idna==3.2
 imagesize==1.2.0
+importlib-metadata==4.11.3
 install==1.3.4
+ipykernel==6.12.1
+ipython==8.2.0
+ipython-genutils==0.2.0
+ipywidgets==7.7.0
+jedi==0.18.1
 Jinja2==3.0.1
+jsonschema==4.4.0
+jupyter==1.0.0
+jupyter-client==7.2.1
+jupyter-console==6.4.3
+jupyter-core==4.9.2
+jupyterlab-pygments==0.1.2
+jupyterlab-widgets==1.1.0
+link==2.1.3
 markdown-it-py==1.1.0
 MarkupSafe==2.0.1
+matplotlib-inline==0.1.3
 mdit-py-plugins==0.2.8
+mistune==0.8.4
 myst-parser==0.15.2
+nbclient==0.5.13
+nbconvert==6.4.5
+nbformat==5.3.0
+nest-asyncio==1.5.5
+notebook==6.4.10
+numpy==1.22.3
+oauthlib==3.2.0
 packaging==21.0
+pandas==1.4.2
+pandocfilters==1.5.0
+parso==0.8.3
+pexpect==4.8.0
+pickleshare==0.7.5
+prometheus-client==0.13.1
+prompt-toolkit==3.0.29
+protobuf==3.19.4
+psutil==5.9.0
+ptyprocess==0.7.0
+pure-eval==0.2.2
+pycparser==2.21
 Pygments==2.10.0
 pyparsing==2.4.7
+pyrsistent==0.18.1
+python-dateutil==2.8.2
 pytz==2021.1
 PyYAML==5.4.1
+pyzmq==22.3.0
+qtconsole==5.3.0
+QtPy==2.0.1
 requests==2.26.0
+requests-oauthlib==1.3.1
+Send2Trash==1.8.0
+six==1.16.0
 snowballstemmer==2.1.0
-Sphinx==4.1.2
+soupsieve==2.3.1
+Sphinx==4.5.0
 sphinx-rtd-theme==0.5.2
 sphinxcontrib-applehelp==1.0.2
 sphinxcontrib-devhelp==1.0.2
 sphinxcontrib-htmlhelp==2.0.0
 sphinxcontrib-jsmath==1.0.1
 sphinxcontrib-qthelp==1.0.3
 sphinxcontrib-serializinghtml==1.1.5
+stack-data==0.2.0
+terminado==0.13.3
+testpath==0.6.0
+tornado==6.1
+traitlets==5.1.1
 urllib3==1.26.6
-furo==2021.11.16
-
+wcwidth==0.2.5
+webencodings==0.5.1
+widgetsnbextension==3.6.0
+xmltodict==0.12.0
+zipp==3.8.0

source/overview.rst → source/about-rhomis/overview.rst

@@ -3,6 +3,8 @@
 What is RHoMIS?
 ===================================================
 
+   `RHoMIS App <appLink>`_.
+
 Module Library
 #####################################
 

source/contributor-guide/contributor-guide.rst

@@ -0,0 +1,2 @@
+Contributor Guide
+================================

source/developer-guide.rst → source/developer-guide/developer-guide.rst

@@ -46,7 +46,7 @@ Code Repositories
 
 Summary of the RHoMIS 2.0 System
 -------------------------------------------
-.. figure:: images/system_summary.png
+.. figure:: ../images/system_summary.png
 
     A summary of the RHoMIS 2.0 system components
     and how they interact.
@@ -78,7 +78,7 @@ works for key processes.
 Survey creation
 ********************************
 
-.. figure:: images/building_survey.png
+.. figure:: ../images/building_survey.png
 
     A summary of how components interact for the "survey creation" process.
     Irrelevant components and interactions have been blacke/greyed out.
@@ -97,7 +97,7 @@ Survey creation
 Data collection
 ******************************
 
-.. figure:: ./images/collecting_data.png
+.. figure:: ../images/collecting_data.png
 
     Data collection schematic.
 
@@ -113,7 +113,7 @@ For data collection and the management of raw data RHoMIS 2.0 currently relies o
 Data processing
 *******************************
 
-.. figure:: images/processing_data.png
+.. figure:: ../images/processing_data.png
 
     Schematic of processing steps
 
@@ -137,6 +137,6 @@ Querying and Download
 #. This user token is then sent to the RHoMIS data API and decoded to identify the relevant user.
 #. The user is then able to access their own project data and project-metadata through the API.
 
-.. image:: images/querying_data.png
+.. image:: ../images/querying_data.png
 
 

source/survey-builder-dev.rst → source/developer-guide/survey-builder-dev.rst

@@ -1,6 +1,6 @@
 .. _survey_builder_dev:
 
-Survey Builder 
+Contributor Guide
 ==================================
 
 Essential information
@@ -22,7 +22,7 @@ The survey builder gives information to the following components of RHoMIS 2.0:
 Processes
 ------------------------------------
 
-.. image:: images/survey_builder_process.png
+.. image:: ../images/survey_builder_process.png
 
 We begin by the user registering to use RHoMIS through the authentication server. The user sends a request with their email and password. They are then assigned an ID and their password is hashed and stored. When logging in, the user gives their email and password. This is verified, and a token is returned to the authenticated user. This token is decoded by the survey builder, and the user ID is stored locally in the survey builder database. 
 
@@ -36,12 +36,12 @@ Database
 Projects Users and Forms
 ************************************
 
-.. image:: images/users_forms_projects.png
+.. image:: ../images/users_forms_projects.png
 
 
 Survey Module 
 ************************************
 
-.. image:: images/survey_modules.png
+.. image:: ../images/survey_modules.png