Merge pull request #69 from UCL-CORU/docs-formatting

Docs formatting

Author: zmek

README.md

@@ -99,6 +99,21 @@ pip install -e ".[test]" #this will install the code in test mode
 
 ```
 
+### Development Installation (optional)
+
+If you plan to contribute to the project or run documentation locally, install the development and documentation dependencies:
+
+```sh
+# For development tools (linting, formatting, etc.)
+pip install -e ".[dev]"
+
+# For building documentation
+pip install -e ".[docs]"
+
+# For both development and documentation
+pip install -e ".[dev,docs]"
+```
+
 Navigate to the patientflow folder and run tests to confirm that the installation worked correctly. This command will only work from the root repository. (To date, this has only been tested on Linux and Mac OS machines. If you are running Windows, there may be errors we don't know about. Please raise an issue on Github in that case.)
 
 ```sh
@@ -107,7 +122,21 @@ pytest
 
 If you get errors running the pytest command, there may be other installations needed on your local machine.
 
-### Using the notebooks in this repository
+### Building and Viewing Documentation (optional)
+
+After installing the documentation dependencies, you can build and view the documentation locally:
+
+```sh
+# Build and serve the documentation with live reloading
+mkdocs serve
+
+# Or just build the documentation
+mkdocs build
+```
+
+The documentation will be available at http://127.0.0.1:8000/ when using `mkdocs serve`.
+
+## Using the notebooks in this repository
 
 The notebooks in this repository demonstrate the use of some of the functions provided in `patientflow`. The cell output shows the results of running the notebooks. If you want to run them yourself, you have two options
 
@@ -127,6 +156,55 @@ python -m patientflow.train.emergency_demand --data_folder_name=data-synthetic
 
 The `data_folder_name`argument specifies the name of the folder containing data. The function expects this folder to be directly below the root of the repository.
 
+## Contributing to PatientFlow
+
+We welcome contributions to the patientflow project. To contribute, follow the instructions below.
+
+### Development Workflow
+
+1. Fork the repository on GitHub
+2. Clone your fork locally and set up your development environment following the [installation instructions](#installation) above, making sure to install the development dependencies.
+3. Create a new branch for your changes:
+   ```sh
+   git checkout -b feature/your-feature-name
+   ```
+4. Make your changes following the code style guidelines
+5. Run tests as described in the installation section to ensure your changes don't break existing functionality
+6. Update documentation if needed using the documentation tools mentioned above
+7. Commit your changes with a descriptive message
+
+### Code Style Guidelines
+
+- Follow PEP 8 guidelines for Python code
+- Use type hints where appropriate
+- Write docstrings for all functions, classes, and modules
+- Add unit tests for new functionality
+
+### Submitting Your Contribution
+
+1. Push your changes to your forked repository:
+   ```sh
+   git push origin feature/your-feature-name
+   ```
+2. Open a pull request from your fork to the main repository
+   - Provide a clear title and description
+   - Reference any relevant issues
+   - Include screenshots if applicable
+3. Address any feedback or review comments
+
+### Reporting Issues
+
+If you find a bug or have a suggestion:
+
+1. Check existing issues to avoid duplicates
+2. Open a new issue describing:
+   - What you expected to happen
+   - What actually happened
+   - Steps to reproduce
+   - Your environment details (OS, Python version, etc.)
+
+Thank you for contributing!
+
 ## Roadmap
 
 - [x] Initial Research
@@ -136,7 +214,7 @@ The `data_folder_name`argument specifies the name of the folder containing data.
 
 ### Project Team
 
-- [Dr Zella King](https://github.com/zmek), Clinical Operational Research Unit (CORU), University College London ([zella.king@ucl.ac.uk](mailto:zella.king@ucl.ac.uk))
+- [Dr Zella King](https://github.com/zmek), Clinical Operational Research Unit (CORU), University College London (UCL)([zella.king@ucl.ac.uk](mailto:zella.king@ucl.ac.uk))
 - [Jon Gillham](https://github.com/jongillham), Institute of Health Informatics, UCL
 - Professor Sonya Crowe, CORU
 - Professor Martin Utley, CORU

docs/notebooks/4c_Evaluate_emergency_demand_predictions.md

@@ -401,7 +401,7 @@ The haematology/oncology and paediatric models have show a stepwise pattern of s
 
 However, the narrow, peaked histograms for these specialties suggest consistent, small overestimations rather than wild inaccuracy, which is a reasonable outcome given the small sample sizes.
 
-## ## Generate predicted distributions and observed number of admissions for each specialty and prediction time for patients yet-to-arrive to the ED
+## Generate predicted distributions and observed number of admissions for each specialty and prediction time for patients yet-to-arrive to the ED
 
 As the predictions for yet-to-arrive patients are aspirational, these cannot be directly compared with observed numbers of patients who arrived after the moment of prediction, and were admitted within the prediction window. Due to slower than target processing of patients through the ED, these future arrivals would have a smaller likelihood of being admitted within the window than suggested by the aspirational target.
 

docs/overrides/main.html

@@ -0,0 +1,31 @@
+{% extends "base.html" %} {% block extrahead %}
+<style>
+  /* Make dataframe tables scroll horizontally when they're too wide */
+  .md-typeset .dataframe {
+    display: block;
+    width: 100%;
+    max-width: 100%;
+    overflow-x: auto;
+    white-space: nowrap;
+    margin-bottom: 1rem;
+    border-collapse: collapse;
+  }
+
+  /* Handle table containers */
+  .md-typeset div table {
+    display: table;
+    width: 100%;
+  }
+
+  /* Ensure code outputs don't overflow */
+  .md-content__inner pre {
+    overflow-x: auto;
+    max-width: 100%;
+  }
+
+  /* Images should not overflow */
+  .md-typeset img {
+    max-width: 100%;
+  }
+</style>
+{% endblock %}

mkdocs.yml

@@ -15,6 +15,7 @@ validation:
 
 theme:
   name: "material"
+  custom_dir: docs/overrides
   features:
     - content.action.edit
   palette:

notebooks/4c_Evaluate_emergency_demand_predictions.ipynb

@@ -615,7 +615,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## ## Generate predicted distributions and observed number of admissions for each specialty and prediction time for patients yet-to-arrive to the ED\n",
+    "## Generate predicted distributions and observed number of admissions for each specialty and prediction time for patients yet-to-arrive to the ED\n",
     "\n",
     "As the predictions for yet-to-arrive patients are aspirational, these cannot be directly compared with observed numbers of patients who arrived after the moment of prediction, and were admitted within the prediction window. Due to slower than target processing of patients through the ED, these future arrivals would have a smaller likelihood of being admitted within the window than suggested by the aspirational target. \n",
     "\n",

pyproject.toml

@@ -35,6 +35,8 @@ optional-dependencies = {dev = [
 ], docs = [
     "griffe",
     "mkdocs",
+    "mkdocs-autorefs",
+    "mkdocs-awesome-pages-plugin",
     "mkdocs-include-markdown-plugin",
     "mkdocs-material",
     "mkdocstrings",

requirements.txt

@@ -1,5 +1,4 @@
 matplotlib>=3.1.3
-mkdocs-awesome-pages-plugin>=2.8.0
 numpy>=1.18.1
 pandas>=1.0.1
 PyYAML==6.0.2