Updated documentation

.gitignore

@@ -4,4 +4,5 @@ build
 dist
 __pycache__/
 *.py[cod]
-.idea/*
+.idea/*
+jupyter_execute/

README.md

@@ -1,135 +1,35 @@
+<!-- begin intro -->
+
 # ChemREL
 
 Automate and transfer chemical data extraction using span categorization and relation extraction models.
 
 ## Introduction
 
-ChemREL is a PIP package that allows you to train chemical data extraction models with ease using a suite of models,
+ChemREL is a PyPI (pip) package that allows you to train chemical data extraction models with ease using a suite of models,
 configurations, and data processing methods. ChemREL consists of a command line interface (CLI) through which you can
 run various commands, as well as a collection of different functions that you can import into your own code.
 
-When utilizing or sharing the dataset and models, kindly note that they are governed under the CC BY NC 4.0 license as imposed by software and data mining guidelines, permitting only non-commercial applications. They should exclusively be used for research. Any alterations to the models, datasets, or methods must be properly attributed with the following [ChemREL citation](#citation).
+When utilizing or sharing the dataset and models included with ChemREL, kindly note that they are governed under the CC BY NC 4.0 license as imposed
+by software and data mining guidelines, permitting only non-commercial applications. They should be used exclusively for research.
+<!-- end intro -->
+Any alterations to the models, datasets, or functions included with ChemREL must be properly attributed using the [citation](#citation) provided in this documentation.
+
+## Documentation
 
-### Documentation
+To view the full installation and usage reference for ChemREL, visit [ChemREL's documentation](docs/index.html).
 
-To install and set up ChemREL, see the [Setup](#setup) section of this file. The following are also provided as
-additional documentation.
+The reference material on the documentation website can be additionally found as follows.
 
 + [ChemREL CLI Reference](chemrel/README.md) - Complete documentation of all available CLI commands.
-+ [ChemREL Methods Reference](https://peesegroup.github.io/ChemREL/) - Complete documentation of ChemREL Python methods which
++ [ChemREL Functions Reference](https://peesegroup.github.io/ChemREL/functions_index.html) - Complete documentation of ChemREL Python functions which
 are intended to be importable in your own code.
-+ [Toy Jupyter Notebook](toy_notebook.ipynb) - Jupyter notebook demonstrating usage of importable prediction functions.
-
-## Setup
-ChemREL can be installed via the command line from the PyPI index using the `pip install` command. Once installed, the
-ChemREL CLI can be invoked from any directory in the command line using the `chemrel` command (but you should `cd` into
-the proper directory first, as described below).
-
-### Virtual Environment
-
-To ensure that the `chemrel` keyword is recognized by your system, it is recommended that you create a new virtual
-environment before installing ChemREL. To do so, open the command line and run the following.
-```console
-python -m venv venv
-```
-
-Next, activate the environment by running 
-```console
-source venv/bin/activate
-```
-if using a MacOS (unix-like) or Linux machine, or
-```console
-venv\Scripts\activate
-```
-if using a Windows machine. Your virtual environment should now be active, and the prompt in the command line should be 
-prefaced by the name of your environment, `venv`.
-
-### GPU Commands
-
-If you plan to use ChemREL CLI commands to train on a CUDA-enabled GPU, you should install versions of Spacy and PyTorch
-which have been compiled with CUDA enabled before installing ChemREL. To do so, within the command line and within your
-virtual environment, run the installation commands generated by the 
-[PyTorch quickstart site](https://pytorch.org/get-started/locally/) and the
-[Spacy quickstart site](https://spacy.io/usage) after selecting your applicable preferences. Once the PyTorch and Spacy 
-installations have been completed, proceed to the next step.
-
-Note: If you do not install versions CUDA-enabled versions of Spacy and PyTorch before installing ChemREL, all GPU-related commands will fail.
-
-### Installation
-
-Now, to install ChemREL in the environment, run the following.
-```console
-pip install chemrel
-```
-
-Next, run the following to ensure that ChemREL has been properly installed. A help prompt should display.
-```console
-chemrel --help
-```
-
-Before running any model-related commands, ChemREL must be initialized by downloading all necessary model and config
-files required by the package. To download the files to your desired directory, first enter the directory where you wish
-to save the files by running the `cd` command in the command line as follows, where `[PATH]` should be replaced
-with the directory path of your desired location. Note that you will need to `cd` into this directory before using
-ChemREL in the future.
-```console
-cd [PATH]
-```
-You can then run the `pwd` command to print the path you have entered to verify that you are in the correct directory.
-
-Next, run the following command to download the required files. The files will be downloaded in the folder path you
-previously entered. This may take a while to complete.
-```console
-chemrel init
-```
-Note: You can also install the files to a path relative to the currently focused directory by passing an additional
-argument into the command, e.g. `chemrel init [ALTERNATE PATH]`.
-
-Note for Windows installations: If the `chemrel init` command hangs while downloading required files, you can
-alternatively clone the contents of the
-[`chemrelmodels` Hugging Face repository](https://huggingface.co/AbdulelahAlshehri/chemrelmodels/tree/main) to the same 
-directory.
-
-Once the initialization is complete, you are ready to begin using ChemREL.
-
-## Usage
-
-### Calling the CLI
-
-Before using any ChemREL CLI commands, always make sure to `cd` into the directory in which you initialized ChemREL as
-follows, where `[PATH]` is the directory path in which you originally ran the `chemrel init` command.
-```console
-cd [PATH]
-```
-Otherwise, the necessary files will not be visible to the program.
++ [Prediction Functions Demo Notebook](docs_src/notebooks/predict.ipynb) - Jupyter notebook demonstrating usage of importable prediction functions.
 
-To print the help text for any command or subcommand, simply enter the desired command followed by the `--help` flag.
-For example, the following will print the help text for the `chemrel predict` command.
-```console
-chemrel predict --help
-```
-
-View the [ChemREL CLI Reference](chemrel/README.md) for a full list of available CLI commands.
-
-### Importing Methods
-
-In addition to the CLI, the ChemREL PIP package exposes a number of functions which can be imported from within your own
-code.
-You must first import the specific submodule containing your desired function from the `functions` package. For example,
-to import the `auxiliary` submodule, run the following line.
-```python
-from chemrel.functions import auxiliary
-```
+<!-- begin citation -->
 
-You can then reference any available functions within the `auxiliary` submodule. For example, to call the
-`extract_paper()` function, you can run the following.
-```python
-paper = auxiliary.extract_paper("/example/paper/path")
-```
-
-View the [ChemREL Methods Reference](https://peesegroup.github.io/ChemREL/) for a full list of importable methods.
-
-### Citation
+## Citation
+Any alterations to the models, datasets, or functions included with ChemREL must be properly attributed according to the following citation.
 ```
 @article{doi,
   author = {Alshehri, Abdulelah S. and Horstmann, Kai A. and You, Fengqi},
@@ -145,3 +45,5 @@ View the [ChemREL Methods Reference](https://peesegroup.github.io/ChemREL/) for
   abstract = {Abstract}
 }
 ```
+
+<!-- end citation -->

chemrel/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 PEESE
+Copyright (c) 2024 PEESE
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

docs/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 3dae10dbd3d8e49364bffe7f587fb124
+config: 3aeac4334ddae1d4ee491dadd1fd1e78
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_sources/cli.md.txt

@@ -0,0 +1,9 @@
+# CLI Reference
+
+The following reference provides documentation for all commands, options, and arguments available via the ChemREL Command Line Interface (CLI).
+
+---
+
+```{include} ../chemrel/README.md
+:heading-offset: 1
+```

docs/_sources/functions_index.md.txt

@@ -0,0 +1,18 @@
+# Functions Reference
+
+This reference provides comprehensive documentation for all Python methods which are intended to be importable within your own code.
+All such functions are part of the `functions` module, viewable below. Two main submodules exist, the `auxiliary` and `predict` modules.
+For more information on how to import and use the provided functions, view the [Importing Functions](usage.md#importing-functions) section of the documentation.
+
+```{toctree}
+:maxdepth: 3
+:caption: "Package Contents:"
+
+functions
+```
+
+## Package Index
+
+The following index lists all available methods in the `functions` module.
+
++ {ref}`genindex`

docs/_sources/index.md.txt

@@ -0,0 +1,33 @@
+```{include} ../README.md
+:start-after: <!-- begin intro -->
+:end-before: <!-- end intro -->
+```
+```{admonition} Notice
+:class: seealso
+Any alterations to the models, datasets, or methods included with ChemREL must be properly attributed using the [citation](usage.md#citation) provided in this documentation.
+```
+To install and begin using ChemREL, proceed to the [Setup](setup) section.
+
+```{toctree}
+:hidden:
+:caption: Getting Started
+
+Welcome <self>
+setup
+usage
+```
+
+```{toctree}
+:hidden:
+:caption: Reference
+
+cli
+functions_index
+```
+
+```{toctree}
+:hidden:
+:caption: Example Notebooks
+
+notebooks/predict
+```

toy_notebook.ipynb → docs/_sources/notebooks/predict.ipynb.txt

@@ -4,10 +4,21 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# ChemREL Toy Notebook\n",
-    "This notebook demonstrates the usage of the prediction functions that are part of ChemREL."
+    "# Prediction Functions Demo\n",
+    "This Jupyter notebook demonstrates the usage of the prediction functions that are part of ChemREL."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "source": [
+    ":::{tip}\n",
+    "To run a copy of this notebook yourself, download a copy of the `.ipynb` file [here](https://github.com/PEESEgroup/ChemREL/blob/main/docs_src/notebooks/predict.ipynb).\n",
+    ":::"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -35,7 +46,7 @@
    "metadata": {},
    "source": [
     "## Predict Submodule\n",
-    "The `predict` submodule contains two available functions, `predict_span()` and `predict_rel()`. Their usage is demonstrated below. For the full documentation of each method, see the [ChemREL Methods Reference](https://hl3c.github.io/ChemREL)."
+    "The `predict` submodule contains two available functions, `predict_span()` and `predict_rel()`. Their usage is demonstrated below. For the full documentation of each function, see the [ChemREL Functions Reference](https://hl3c.github.io/ChemREL)."
    ]
   },
   {

docs/_sources/setup.md.txt

@@ -0,0 +1,81 @@
+# Setup
+ChemREL can be installed via the command line from the PyPI index using the `pip install` command. Once installed, the
+ChemREL CLI can be invoked from any directory in the command line using the `chemrel` command (but you should `cd` into
+the proper directory first, as described below).
+
+## Virtual Environment
+
+To ensure that the `chemrel` keyword is recognized by your system, it is recommended that you create a new virtual
+environment before installing ChemREL. To do so, open the command line and run the following.
+```console
+$ python -m venv venv
+```
+
+Next, if using a MacOS (unix-like) or Linux machine, activate the environment by running 
+```console
+$ source venv/bin/activate
+```
+or if using a Windows machine, run
+```console
+$ venv\Scripts\activate
+```
+instead. Your virtual environment should now be active, and the prompt in the command line should be 
+prefaced by the name of your environment, `venv`.
+
+## GPU Commands
+
+If you plan to use ChemREL CLI commands to train on a CUDA-enabled GPU, you should install versions of Spacy and PyTorch
+which have been compiled with CUDA enabled before installing ChemREL. To do so, within the command line and within your
+virtual environment, run the installation commands generated by the 
+[PyTorch quickstart site](https://pytorch.org/get-started/locally/) and the
+[Spacy quickstart site](https://spacy.io/usage) after selecting your applicable preferences. Once the PyTorch and Spacy 
+installations have been completed, proceed to the next step.
+
+```{caution}
+If you do not install CUDA-enabled versions of Spacy and PyTorch before installing ChemREL, all GPU-related commands will fail by default.
+
+```
+
+## Installation
+
+Now, to install ChemREL in the environment, run the following.
+```console
+$ pip install chemrel
+```
+
+Next, run the following to ensure that ChemREL has been properly installed. A help prompt should display.
+```console
+$ chemrel --help
+```
+
+Before running any model-related commands, ChemREL must be initialized by downloading all necessary model and config
+files required by the package. To download the files to your desired directory, first enter the directory where you wish
+to save the files by running the `cd` command in the command line as follows, where `[PATH]` should be replaced
+with the directory path of your desired location.
+```console
+$ cd [PATH]
+```
+```{note}
+Note that you will need to `cd` into this directory before using ChemREL in the future.
+```
+
+You can then run the `pwd` command to print the path you have entered to verify that you are in the correct directory.
+
+Next, run the following command to download the required files. The files will be downloaded in the folder path you
+previously entered. This may take a while to complete.
+```console
+$ chemrel init
+```
+```{tip}
+You can also install the files to a path relative to the currently focused directory by passing an additional
+argument into the command, e.g. `chemrel init [ALTERNATE PATH]`.
+```
+```{admonition} Note for Windows installations
+:class: note
+If the `chemrel init` command hangs while downloading required files, you can
+alternatively clone the contents of the
+[`chemrelmodels` Hugging Face repository](https://huggingface.co/AbdulelahAlshehri/chemrelmodels/tree/main) to the same 
+directory.
+```
+
+Once the initialization is complete, you are ready to begin using ChemREL.