Merge pull request #279 from CITCOM-project/doc-revamp

Documentation Revamp

Author: f-allian

README.md

@@ -24,9 +24,101 @@ system-under-test that is expected to cause a change to some output(s).
 
 ## Installation
 
-See the Read the Docs site for [installation
-instructions](https://causal-testing-framework.readthedocs.io/en/latest/installation.html).
+### Requirements
+- Python 3.9 and 3.10 only.
 
-## Documentation
+- Microsoft Visual C++ 14.0+ (Windows only).
 
-Further information on causal inference, the code, usage and more can be found on the [docs](https://causal-testing-framework.readthedocs.io/en/latest/)
+To install the latest stable release of the Causal Testing Framework:
+
+``pip install causal-testing-framework``
+
+or if you want to install with the development packages/tools:
+
+``pip install causal-testing-framework[dev]``
+
+Alternatively, you can install directly via source:
+
+```shell
+git clone https://github.com/CITCOM-project/CausalTestingFramework
+cd CausalTestingFramework
+```
+then to install a specific release:
+
+```shell
+git fetch --all --tags --prune
+git checkout tags/<tag> -b <branch>
+pip install . # For core API only
+pip install -e . # For editable install, useful for development work
+```
+For more information on how to use the Causal Testing Framework, please refer to our [documentation](https://causal-testing-framework.readthedocs.io/en/latest/?badge=latest).  
+## How to Cite
+If you use our framework in your work, please cite the following:
+
+``This research has used version X.Y.Z (software citation) of the 
+Causal Testing Framework (paper citation).``
+
+The paper citation should be the Causal Testing Framework [paper](https://dl.acm.org/doi/10.1145/3607184), 
+and the software citation should contain the specific Figshare [DOI](https://orda.shef.ac.uk/articles/software/CITCOM_Software_Release/24427516) of the version used in your work.
+
+
+
+<details>
+  <summary><b>BibTeX Citations</b></summary>
+  
+  <details>
+    <summary>Paper</summary>
+    
+    ```
+    @ARTICLE{Clark_etal_2023,
+    author = {Clark, Andrew G. and Foster, Michael and Prifling, Benedikt and Walkinshaw, Neil and Hierons, Robert M.
+    and Schmidt, Volker and Turner, Robert D.},
+    title = {Testing Causality in Scientific Modelling Software},
+    year = {2023},
+    publisher = {Association for Computing Machinery},
+    url = {https://doi.org/10.1145/3607184},
+    doi = {10.1145/3607184},
+    journal = {ACM Trans. Softw. Eng. Methodol.},
+    month = {jul},
+    keywords = {Software Testing, Causal Testing, Causal Inference}
+    }
+    ```
+
+  </details>
+  
+  <details>
+    <summary>Software (example)</summary>
+    
+    ```
+    @ARTICLE{Wild2023,
+    author = {Foster, Michael and Clark, Andrew G. and Somers, Richard and Wild, Christopher and Allian, Farhad and Hierons, Robert M. and Wagg, David and Walkinshaw, Neil},
+    title = {CITCOM Software Release},
+    year = {2023},
+    month = {nov},
+    url = {https://orda.shef.ac.uk/articles/software/CITCOM_Software_Release/24427516},
+    doi = {10.15131/shef.data.24427516.v1}
+    }
+    ```
+  </details>
+
+</details>
+
+## How to Contribute
+
+To contribute to our work, please ensure the following:
+
+1. [Fork the repository](https://help.github.com/articles/fork-a-repo/) into your own GitHub account, and [clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) it to your local machine.
+2. [Create a new branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository) in your forked repository. Give this branch an appropriate name, and create commits that describe the changes.
+3. [Push your changes](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository) to your new branch in your remote fork, compare with `CausalTestingFramework/main`, and ensure any conflicts are resolved.
+4. Create a draft [pull request](https://docs.github.com/en/get-started/quickstart/hello-world#opening-a-pull-request) from your branch, and ensure you have [linked](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls) it to any relevant issues in your description. 
+
+We use the [unittest]() module to develop our tests and the [pytest](https://pytest.org/en/latest/) framework as our test discovery, [pylint](https://pypi.org/project/pylint/) for our code analyser, and [black](https://pypi.org/project/black/) for our code formatting.
+To find the other (optional) developer dependencies, please check `pyproject.toml`.
+
+
+
+## Acknowledgements 
+
+The Causal Testing Framework is supported by the UK's Engineering and Physical Sciences Research Council (EPSRC),
+with the project name [CITCOM](https://gow.epsrc.ukri.org/NGBOViewGrant.aspx?GrantRef=EP/T030526/1) - "_Causal Inference for Testing of Computational Models_" 
+under the grant EP/T030526/1.

docs/source/dev/actions_and_webhooks.rst

@@ -4,7 +4,7 @@ Github Actions and Webhooks
 Actions
 --------------
 
-Currently, this project makes use of 3 `Github Actions <https://github.com/features/actions>`_,
+Currently, this project makes use of 4 `Github Actions <https://github.com/features/actions>`_,
 which can be found in the
 `.github/workflows <https://github.com/CITCOM-project/CausalTestingFramework/tree/main/.github/workflows>`_ directory.
 
@@ -16,14 +16,18 @@ They are:
 
 #.  ``publish-to-pypi.yaml``, runs when a new version tag is pushed and publishes that tag version to PyPI.
 
+#. ``figshare.yaml``, releases new versions to `Figshare <https://orda.shef.ac.uk/articles/software/CITCOM_Software_Release/24427516?file=43686015>`_.
+
+#. ``publish-to-dafni.yaml``, which containerises and uploads every major release to `DAFNI <https://www.dafni.ac.uk/>`_.
+
+
 Webhooks
 ---------------
 
-The project also uses 3 `Webhooks <https://docs.github.com/en/webhooks-and-events/webhooks/about-webhooks>`_, which can
+The project also uses 2 `Webhooks <https://docs.github.com/en/webhooks-and-events/webhooks/about-webhooks>`_, which can
 be found in the `project settings <https://github.com/CITCOM-project/CausalTestingFramework/settings>`_ on Github. These
 include:
 
-#.  `Codacy <https://github.com/codacy>`_
 
 #.  `Codecov <https://github.com/codecov>`_
 

docs/source/images/workflow.png

@@ -10,7 +10,6 @@ Causal testing is a :term:`causal inference`-driven framework for functional bla
 graphical causal inference (CI) techniques for the specification and functional testing of software from a black-box
 perspective. In this framework, we use causal directed acyclic graphs (DAGs) to express the anticipated cause-effect
 relationships amongst the inputs and outputs of the system-under-test and the supporting mathematical framework to
-relationships amongst the inputs and outputs of the system-under-test and the supporting mathematical framework to
 design statistical procedures capable of making causal inferences. Each causal test case focuses on the causal effect
 of an intervention made to the system-under test. That is, a prescribed change to the input configuration of the
 system-under-test that is expected to cause a change to some output(s).
@@ -37,7 +36,7 @@ system-under-test that is expected to cause a change to some output(s).
    }
 
    .zoom-container.zoomed {
-       transform: scale(2);
+       transform: scale(4);
        cursor: zoom-out;
    }
 
@@ -84,7 +83,7 @@ system-under-test that is expected to cause a change to some output(s).
 
 .. container:: zoom-container
 
-   .. image:: /images/workflow.png
+   .. image:: /images/schematic.png
       :class: zoomable-image
       :alt: Zoomable Image
 
@@ -93,8 +92,6 @@ system-under-test that is expected to cause a change to some output(s).
    :hidden:
    :caption: Home
 
-   self
-
 .. toctree::
    :hidden:
    :maxdepth: 1

docs/source/index.rst

@@ -3,7 +3,7 @@ Getting started
 
 Requirements
 ---------------
-* Python >= 3.9.
+* Python 3.9 and 3.10 only.
 * `Microsoft Visual C++ <https://docs.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist>`_ 14.0+ (Windows only).
 
 

docs/source/installation.rst

@@ -6,6 +6,6 @@ To run this case study:
 1. Ensure all project dependencies are installed by running `pip install .` in the top level directory
    (instructions are provided in the project README).
 2. Change directory to `causal_testing/examples/poisson-line-process`.
-3. Run the command `python test_poisson_process.py`
+3. Run the command `python example_poisson_process.py`
 
 This should print a series of causal test results and produce two CSV files. `intensity_num_shapes_results_random_1000.csv` corresponds to table 1, and `width_num_shapes_results_random_1000.csv` relates to our findings regarding the relationship of width and `P_u`.