Restructure docs and update README

.github/workflows/docs.yml

@@ -0,0 +1,31 @@
+name: Build Docs
+
+on:
+  workflow_dispatch:
+  push:
+    branches: ["main"]
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.9"
+      - name: Install dependencies
+        run: |
+          curl -sSL https://install.python-poetry.org | python - --version 1.3.2
+          poetry install --with docs --all-extras
+          echo "PYTHONPATH=`pwd`" >> $GITHUB_ENV
+      - name: Build Docs
+        run: |
+          sudo apt-get update -y && sudo apt-get install -y pandoc python3-pkg-resources python3-setuptools
+          poetry run sphinx-build -b html -a docs docs/site
+      - name: Deploy docs
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/site

.gitignore

@@ -143,3 +143,4 @@ docs/**/*.png
 docs/**/*.jpg
 docs/**/*.gif
 docs/site/
+docs/_examples/

CODE_OF_CONDUCT.md

@@ -1,4 +1,4 @@
-# Contributor Covenant Code of Conduct
+# Code of Conduct
 
 ## Our Pledge
 
@@ -116,13 +116,13 @@ the community.
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage],
 version 2.0, available at
-https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+<https://www.contributor-covenant.org/version/2/0/code_of_conduct.html>.
 
 Community Impact Guidelines were inspired by [Mozilla's code of conduct
 enforcement ladder](https://github.com/mozilla/diversity).
 
 [homepage]: https://www.contributor-covenant.org
 
 For answers to common questions about this code of conduct, see the FAQ at
-https://www.contributor-covenant.org/faq. Translations are available at
-https://www.contributor-covenant.org/translations.
+<https://www.contributor-covenant.org/faq>. Translations are available at
+<https://www.contributor-covenant.org/translations>.

CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing
+
+PyDicer welcomes any and all contributions in the way of new functionality, bug fixes or documentation. This document provides some guidance to developers who would like to contribute to the project.
+
+## Git
+
+Create a branch off of **main** while you make your changes or implement your new tool.
+Once complete, head to  [GitHub to create a pull
+request](https://github.com/australiancancerdatanetwork/pydicer/compare) to merge your changes
+into the **main** branch. At this point the automated tests will run and maintainers will review
+your submission before merging.
+
+## Poetry
+
+PyDicer uses poetry to manage dependencies. Instructions for installing poetry are available
+[here](https://python-poetry.org/docs/#installation). Once installed, you can easily install the
+libraries required to develop for PyDicer using the following command:
+
+```bash
+poetry install --with dev,docs --all-extras
+```
+
+This will automatically create a virtual environment managed by poetry. To run a script within this
+environment, use the `poetry run` followed by what to run. For example, to run a test.py script:
+
+```bash
+poetry run python test.py
+```
+
+## Coding standards
+
+Code in PyDicer must conform to Python's PEP-8 standards to ensure consistent formatting between contributors. To ensure this, pylint is used to check code conforms to these standards before a Pull Request can be merged. You can run pylint from the command line using the following command:
+
+```bash
+pylint pydicer
+```
+
+But a better idea is to ensure you are using a Python IDE which supports linting (such as [VSCode](https://code.visualstudio.com/docs/python/linting) or PyCharm). Make sure you resolve all suggestions from pylint before submitting your pull request.
+
+If you're new to using pylint, you may like to [read this guide](https://docs.pylint.org/en/v2.11.1/tutorial.html).
+
+## Automated tests
+
+A test suite is included in PyDicer which ensures that code contributed to the repository functions as expected and continues to function as further development takes place. Any code submitted via a pull request should include appropriate automated tests for the new code.
+
+pytest is used as a testing library. Running the tests from the command line is really easy:
+
+```bash
+pytest
+```
+
+Add your tests to the appropriate file in the `tests/` directory. See the [pytest documention](https://docs.pytest.org/en/6.2.x/getting-started.html) for more information.

README.md

@@ -1,31 +1,26 @@
-# pydicer: PYthon Dicom Image ConvertER
+# PyDicer: PYthon Dicom Image ConvertER
 
-> ## CAUTION: This tool is currently under development
->
-> This README currently provides some advice for contributing to this repository.
+Welcome to pydicer, a tool to ease the process of converting DICOM data objects into a format typically used for research purposes. In addition to data conversion, functionality is provided to help analyse the data such as the computing radiomic features or radiotherapy dose metrics. PyDicer uses the NIfTI format to store data is a well defined file system structure. Tracking of these data objects in CSV files, also stored on the file system, provides an easy and flexible way to work with the converted data in your research.
 
-Welcome to pydicer, a tool to ease the process of converting DICOM data objects into a format typically used for research purposes. Currently pydicer support conversion to NIfTI format, but it can easily be extended to convert to other formats as well (contributions are welcome).
+## Installation
 
-## Requirements
-
-pydicer currently supports Python 3.7, 3.8 and 3.9. Make sure you install the library and developer requirements:
+PyDicer currently supports Python version 3.8, 3.9 and 3.10. Install PyDicer in your Python
+environment using `pip`:
 
 ```bash
-pip install -r requirements.txt
-pip install -r requirements-dev.txt
+pip install pydicer
 ```
 
-## pydicer Directory Structure
+## Directory Structure
 
-pydicer will place converted and intermediate files into a specific directory structure. Within a pydicer working directory `[working]`, the following directories will be generated:
+pydicer will place converted and intermediate files into a specific directory structure. Within the configured working directory `[working]`, the following directories will be generated:
 
-- `[working]/dicom`: Directory in which DICOM data will be placed and fetched for conversion
 - `[working]/data`: Directory in which converted data will be placed
 - `[working]/quarantine`: Files which couldn't be preprocessed or converted will be placed in here for you to investigate further
 - `[working]/.pydicer`: Intermediate files as well as log output will be stored in here
 - `[working]/[dataset_name]`: Clean datasets prepared using the Dataset Preparation Module will be stored in a directory with their name and will symbolically link to converted in the `[working]/data` directory
 
-## pydicer Pipeline
+## Pipeline
 
 The pipeline handles fetching of the DICOM data to conversion and preparation of your research dataset. Here are the key steps of the pipeline:
 
@@ -41,6 +36,8 @@ The pipeline handles fetching of the DICOM data to conversion and preparation of
 
 6. **Analysis**: Radiomics and Dose Metrics are computed on the converted data.
 
+## Getting Started
+
 Running the pipeline is easy. The following script will get you started:
 
 ```python
@@ -66,26 +63,5 @@ pydicer.add_input(dicom_directory)
 pydicer.run_pipeline()
 ```
 
-## Coding standards
-
-Code in pydicer must conform to Python's PEP-8 standards to ensure consistent formatting between contributors. To ensure this, pylint is used to check code conforms to these standards before a Pull Request can be merged. You can run pylint from the command line using the following command:
-
-```bash
-pylint pydicer
-```
-
-But a better idea is to ensure you are using a Python IDE which supports linting (such as [VSCode](https://code.visualstudio.com/docs/python/linting) or PyCharm). Make sure you resolve all suggestions from pylint before submitting your pull request.
-
-If you're new to using pylint, you may like to [read this guide](https://docs.pylint.org/en/v2.11.1/tutorial.html).
-
-## Automated tests
-
-A test suite is included in pydicer which ensures that code contributed to the repository functions as expected and continues to function as further development takes place. Any code submitted via a pull request should include appropriate automated tests for the new code.
-
-pytest is used as a testing library. Running the tests from the command line is really easy:
-
-```bash
-pytest
-```
-
-Add your tests to the appropriate file in the `tests/` directory. See the [pytest documention](https://docs.pytest.org/en/6.2.x/getting-started.html) for more information.
+or check out the [Getting Started Example](https://australiancancerdatanetwork.github.io/pydicer/_examples/GettingStarted.html).
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/australiancancerdatanetwork/pydicer/blob/main/examples/GettingStarted.ipynb)