Merge remote-tracking branch 'origin/doc-revamp' into doc-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.
 
-## 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 = {Wild, Christopher and Foster, Michael and Walkinshaw, Neil and Clark, Andrew G. and Allian, Farhad and Somers, Richard},
+    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 [pytest](https://pytest.org/en/latest/) framework as our testing suite, [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/index.rst

@@ -93,8 +93,6 @@ system-under-test that is expected to cause a change to some output(s).
    :hidden:
    :caption: Home
 
-   self
-
 .. toctree::
    :hidden:
    :maxdepth: 1

examples/poisson-line-process/README.md

@@ -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`.