Add more Sphinx content, including option list CSV tables

README.md

@@ -59,7 +59,7 @@ This way, `arc.csv` serves not only as a **question bank**, but also as a **meta
 |-------------|-------------------------------------------------------------------------|------------------|-------|--------------|--------------------------|----------------|---------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------|-------------------------------------------------------------|--------------------------------------|------------------|-------------------------------------|
 | Presentation | CO-MORBIDITIES AND RISK FACTORS: Existing prior to this current illness and is ongoing | comor_hypertensi | radio | Hypertension | 1, Yes \| 0, No \| 99, Unknown | Cardiovascular | Defined as elevated arterial blood pressure diagnosed clinically (systolic >140 mmHg and/or diastolic >90 mmHg), or treated with medication. | Indicate 'Yes' if this condition existed prior to admission with this current illness and remains an active medical condition. | SNOMED                      | 38341003, Hypertensive disorder, systemic arterial (disorder) | C0020538, Hypertensive disease       | risk_factor_comor | COVID=1, Dengue=1, Mpox=1, H5Nx=1, ARI=1 |
 
-### `lists/`  
+### `Lists/`  
 A collection of option lists containing standardised reference tables (conditions, demographics, and drugs) that support different response types while ensuring adaptability and consistency in data capture and coding across studies.
 
 ## Data Capture Schema  
@@ -153,11 +153,11 @@ These modules provide shared variables applicable across multiple diseases, impr
 
 ## Files
 
-   - **Clinical Characterization XML:** This XML file provides a recommended configuration and structure for clinical characterization studies. It includes information about users, events, project settings, and functionality, serving as a reference for setting up clinical characterization studies.
+- **Clinical Characterization XML:** This XML file provides a recommended configuration and structure for clinical characterization studies. It includes information about users, events, project settings, and functionality, serving as a reference for setting up clinical characterization studies.
 
-   - **ARC:** The "ARC" file is a machine-readable CSV (Comma-Separated Values) file that forms the core of ARC. It contains a comprehensive list of questions that can be asked in a CRF during outbreaks. Each question is defined with specific parameters, including variable names, coded answers, limits, types, skip logic, and more.
+- **ARC:** The "ARC" file is a machine-readable CSV (Comma-Separated Values) file that forms the core of ARC. It contains a comprehensive list of questions that can be asked in a CRF during outbreaks. Each question is defined with specific parameters, including variable names, coded answers, limits, types, skip logic, and more.
 
-   - **Lists of Standardized Terms:** These files include predefined sets of standardized vocabulary used to describe and categorize various aspects of CRF answers. Standardized terms ensure consistency in data capture, covering items such as comorbidities, symptoms, and medications.
+- **Lists of Standardized Terms:** These files include predefined sets of standardized vocabulary used to describe and categorize various aspects of CRF answers. Standardized terms ensure consistency in data capture, covering items such as comorbidities, symptoms, and medications.
 
 - **Metadata:** For each version of ARC, a version history file is included. This file contains pertinent information about changes made to ARC over time, allowing for easy tracking of modifications. Typical metadata includes the date of upload of the new version and a description of the changes made.
 
@@ -183,6 +183,10 @@ If you want to use ARC for your research or study, follow these steps:
 
 3. **Contributions**: While contributions to the document are limited to authorized users, you can open issues or discussions for questions, suggestions, or clarifications.
 
+## ARC Documentation
+
+Key aspects of ARC, including the core schema, and response option lists, are also documented in HTML [here](https://isaric-arc.readthedocs.io/en/latest/index.html).
+
 ## Contributors
 
 ### Conceptualization

docs/conf.py

@@ -220,6 +220,16 @@
 }
 
 
+html_sidebars = {
+    "**": [
+        "sidebar/scroll-start.html",
+        "sidebar/brand.html",
+        "sidebar/search.html",
+        "sidebar/navigation.html",
+        "sidebar/scroll-end.html",
+    ]
+}
+
 # Force pygments style in dark mode back to the light variant
 pygments_dark_style = "tango"
 

docs/index.rst

@@ -23,14 +23,15 @@ ARC is licensed under the open source compliant `MIT license <https://opensource
 .. image:: _static/osi-badge-light.svg
    :height: 200px
    :width:  200px
+   :target: https://opensource.org/license/mit
 
-For more information use the content links below to navigate to the page(s) of interest.
+Key elements of ARC, including the schema itself, can be explored in more detail below from the linked pages.
 
 .. toctree::
    :maxdepth: 1
    :caption: Contents:
 
-   sources/arc
-   sources/arc-variable-naming
-   sources/arc-field-types
-
+   sources/arc-schema
+   sources/variable-naming
+   sources/special-field-types
+   sources/lists/lists

docs/sources/arc.rst → docs/sources/arc-schema.rst

@@ -4,9 +4,9 @@
 ARC Schema
 ==========
 
-The ARC schema is made available as a machine-readable `CSV <https://github.com/ISARICResearch/ARC/blob/main/ARC.csv>`_ (also shown at the **bottom of this page**) of clinical and research questions. This file provides the standardized structure that ensures interoperability across studies and outbreak contexts.
+The ARC schema is made available as a machine-readable `CSV <https://github.com/ISARICResearch/ARC/blob/main/ARC.csv>`_ (also as a HTML table **at the bottom of this page**) of clinical and research questions. This file provides the standardized structure that ensures interoperability across studies and outbreak contexts.
 
-Each row in the CSV represents a **variable** used in the Case Report Forms (CRFs). Variables include metadata that ensures **clarity, interoperability, and reusability** across contexts. For more details on variable naming conventions see :ref:`this <arc-variable-naming>`, and for details on the variable data types see :ref:`this <arc-field-types>`.
+Each row in the CSV represents a **variable** used in the Case Report Forms (CRFs). Variables include metadata that ensures **clarity, interoperability, and reusability** across contexts. For more details on variable naming conventions see :ref:`this <variable-naming>`, and for details on the variable data types see :ref:`this <special-field-types>`.
 
 For every variable, the following fields are included:
 
@@ -15,11 +15,11 @@ For every variable, the following fields are included:
 - **Section**: Subdivision within the form that groups related questions (e.g., *Co-morbidities and Risk Factors*,…).
 - **Type**: Format of the response field (e.g., ``radio``, ``checkbox``, ``text``, ``date``).
 - **Question**: Human-readable text shown to the data collector (e.g., *Hypertension*).
-- **Answer Options**: Permissible responses to the question. These may reference predefined lists in ``/lists`` (e.g.,
+- **Answer Options**: Permissible responses to the question. These may reference predefined lists in ``/Lists`` (e.g.,
   ``1, Yes | 0, No | 99, Unknown``).
 - **Validation**: Input rules for the response, such as numeric range or pattern restrictions.
 - **Minimum / Maximum**: Boundaries for numeric input when applicable.
-- **List**: Links to option lists in ``/lists``.
+- **List**: Links to option lists in ``/Lists``.
 - **Skip Logic**: Rules defining when the variable should be displayed, depending on other responses.
 - **Body System**: Physiological system the variable belongs to (e.g., *Cardiovascular*).
 - **Definition**: Description of the concept being captured, often linked to clinical definitions.
@@ -35,9 +35,10 @@ The CSV serves not only as a **question bank**, but also as a **metadata diction
 - Mapping to standard vocabularies.
 - Adaptation for different diseases and study contexts.
 
-.. literalinclude:: ../../ARC.csv
-   :encoding: latin-1
-   :language: csv
-   :lineno-start: 1
-   :emphasize-lines: 1
+The raw CSV is presented below as a HTML table - the display is cut off to the right but you can scroll across the table using the touchpad.
 
+.. csv-table::
+    :class: csv-table
+    :file: ../../ARC.csv
+    :header-rows: 1
+    :width: 100%

docs/sources/lists/conditions/comorbidities.rst

@@ -0,0 +1,11 @@
+.. _lists-conditions-comorbidities:
+
+=============
+Comorbidities
+=============
+
+.. csv-table::
+    :class: csv-table
+    :file: ../../../../Lists/conditions/Comorbidities.csv
+    :header-rows: 1
+    :width: 100%

docs/sources/lists/conditions/complications.rst

@@ -0,0 +1,11 @@
+.. _lists-conditions-complications:
+
+=============
+Complications
+=============
+
+.. csv-table::
+    :class: csv-table
+    :file: ../../../../Lists/conditions/Complications.csv
+    :header-rows: 1
+    :width: 100%

docs/sources/lists/conditions/index.rst

@@ -0,0 +1,13 @@
+.. _lists-conditions-index:
+
+Conditions
+==========
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   comorbidities
+   complications
+   sites
+   symptoms

docs/sources/lists/conditions/sites.rst

@@ -0,0 +1,11 @@
+.. _lists-conditions-sites:
+
+====
+Site
+====
+
+.. csv-table::
+    :class: csv-table
+    :file: ../../../../Lists/conditions/Site.csv
+    :header-rows: 1
+    :width: 100%

docs/sources/lists/conditions/symptoms.rst

@@ -0,0 +1,11 @@
+.. _lists-conditions-symptoms:
+
+========
+Symptoms
+========
+
+.. csv-table::
+    :class: csv-table
+    :file: ../../../../Lists/conditions/Symptoms.csv
+    :header-rows: 1
+    :width: 100%

docs/sources/lists/demographics/countries.rst

@@ -0,0 +1,11 @@
+.. _lists-demographics-countries:
+
+=======
+Country
+=======
+
+.. csv-table::
+    :class: csv-table
+    :file: ../../../../Lists/demographics/Country.csv
+    :header-rows: 1
+    :width: 100%

docs/sources/lists/demographics/index.rst

@@ -0,0 +1,12 @@
+.. _lists-demographics-index:
+
+Demographics
+============
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   countries
+   occupations
+   race

docs/sources/lists/demographics/occupations.rst

@@ -0,0 +1,11 @@
+.. _lists-demographics-occupations:
+
+==========
+Occupation
+==========
+
+.. csv-table::
+    :class: csv-table
+    :file: ../../../../Lists/demographics/Occupation.csv
+    :header-rows: 1
+    :width: 100%

docs/sources/lists/demographics/race.rst

@@ -0,0 +1,11 @@
+.. _lists-demographics-race:
+
+====
+Race
+====
+
+.. csv-table::
+    :class: csv-table
+    :file: ../../../../Lists/demographics/Race.csv
+    :header-rows: 1
+    :width: 100%

docs/sources/lists/drugs/antibiotics.rst

@@ -0,0 +1,11 @@
+.. _lists-drugs-antibiotics:
+
+===========
+Antibiotics
+===========
+
+.. csv-table::
+    :class: csv-table
+    :file: ../../../../Lists/drugs/Antibiotics.csv
+    :header-rows: 1
+    :width: 100%

docs/sources/lists/drugs/anticoagulants.rst

@@ -0,0 +1,11 @@
+.. _lists-drugs-anticoagulants:
+
+=============
+Anticoagulant
+=============
+
+.. csv-table::
+    :class: csv-table
+    :file: ../../../../Lists/drugs/Anticoagulant.csv
+    :header-rows: 1
+    :width: 100%

docs/sources/lists/drugs/antifungals.rst

@@ -0,0 +1,11 @@
+.. _lists-drugs-antifungals:
+
+==========
+Antifungal
+==========
+
+.. csv-table::
+    :class: csv-table
+    :file: ../../../../Lists/drugs/Antifungal.csv
+    :header-rows: 1
+    :width: 100%

docs/sources/lists/drugs/antivirals.rst

@@ -0,0 +1,11 @@
+.. _lists-drugs-antivirals:
+
+=========
+Antiviral
+=========
+
+.. csv-table::
+    :class: csv-table
+    :file: ../../../../Lists/drugs/Antiviral.csv
+    :header-rows: 1
+    :width: 100%

docs/sources/lists/drugs/immunosuppressants.rst

@@ -0,0 +1,11 @@
+.. _lists-drugs-immunosuppressants:
+
+==================
+Immunosuppressants
+==================
+
+.. csv-table::
+    :class: csv-table
+    :file: ../../../../Lists/drugs/Immunosuppressants.csv
+    :header-rows: 1
+    :width: 100%

docs/sources/lists/drugs/index.rst

@@ -0,0 +1,18 @@
+.. _lists-drugs-index:
+
+Drugs
+=====
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   antibiotics
+   anticoagulants
+   antifungals
+   antivirals
+   immunosuppressants
+   ivfluids
+   nsaids
+   steroids
+   types

docs/sources/lists/drugs/ivfluids.rst

@@ -0,0 +1,11 @@
+.. _lists-drugs-ivfluids:
+
+=========
+IV Fluids
+=========
+
+.. csv-table::
+    :class: csv-table
+    :file: ../../../../Lists/drugs/IVfluids.csv
+    :header-rows: 1
+    :width: 100%

docs/sources/lists/drugs/nsaids.rst

@@ -0,0 +1,11 @@
+.. _lists-drugs-nsaids:
+
+=======
+NS AIDs
+=======
+
+.. csv-table::
+    :class: csv-table
+    :file: ../../../../Lists/drugs/nsaids.csv
+    :header-rows: 1
+    :width: 100%

docs/sources/lists/drugs/steroids.rst

@@ -0,0 +1,11 @@
+.. _lists-drugs-steroids:
+
+========
+Steroids
+========
+
+.. csv-table::
+    :class: csv-table
+    :file: ../../../../Lists/drugs/Steroids.csv
+    :header-rows: 1
+    :width: 100%

docs/sources/lists/drugs/types.rst

@@ -0,0 +1,11 @@
+.. _lists-drugs-types:
+
+====
+Type
+====
+
+.. csv-table::
+    :class: csv-table
+    :file: ../../../../Lists/drugs/Type.csv
+    :header-rows: 1
+    :width: 100%

docs/sources/lists/followup/index.rst

@@ -0,0 +1,11 @@
+.. _lists-followup-index:
+
+Follow Up
+=========
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   outcome
+   sequelae

docs/sources/lists/followup/outcome.rst

@@ -0,0 +1,11 @@
+.. _lists-followup-outcomes:
+
+=======
+Outcome
+=======
+
+.. csv-table::
+    :class: csv-table
+    :file: ../../../../Lists/followup/outcome.csv
+    :header-rows: 1
+    :width: 100%

docs/sources/lists/followup/sequelae.rst

@@ -0,0 +1,11 @@
+.. _lists-followup-sequelae:
+
+========
+Sequelae
+========
+
+.. csv-table::
+    :class: csv-table
+    :file: ../../../../Lists/followup/sequelae.csv
+    :header-rows: 1
+    :width: 100%