update docs and readme (#244)

* update info about pre-release and its installation * add disk space requirement for installation * add doc about logging * Update README.md - update installation guideline - add guideline for testing * Update docs/index.md Co-authored-by: Giulia Crocioni <[email protected]> * Update docs/install.md Co-authored-by: Giulia Crocioni <[email protected]> * Update docs/logging.md Co-authored-by: Giulia Crocioni <[email protected]> --------- Co-authored-by: Giulia Crocioni <[email protected]>
NPLinker · May 21, 2024 · 6558b46 · 6558b46
1 parent e5e4ecb
commit 6558b46
Show file tree

Hide file tree

Showing 5 changed files with 107 additions and 12 deletions.
diff --git a/README.md b/README.md
@@ -31,22 +31,63 @@ Original paper: [Ranking microbial metabolomic and genomic links in the NPLinker
 
 
 ### Installation
-NPLinker is a Python package, you can install it as following:
+NPLinker is a python package, using both pypi packages and non-pypi packages as dependencies. It 
+requires <span style="color:red;">**~4.5GB**</span> of disk space to install all the dependencies. 
+
 ```shell
-# create a new virtual environment
+# Check python version (requiring ≥3.9)
+python --version
+
+# Create a new virtual environment
 python -m venv env
 source env/bin/activate
 
-# install nplinker package
-pip install nplinker
+# install from nplinker releases (requiring ~300MB of disk space)
+pip install nplinker==2.0.0a1
+
+# or install the latest from source code
+pip install git+https://github.com/nplinker/nplinker@dev 
 
-# install nplinker non-pypi dependencies and databases
+# install nplinker non-pypi dependencies and databases (~4GB)
 install-nplinker-deps
 ```
-
 A virtual environment is *required* to install the the non-pypi dependencies. You can also use `conda`
 to manage python environments.
 
+### Testing
+
+To run the tests, you need to clone this repo and install the development dependencies:
+
+```shell
+# Create a new virtual environment
+python -m venv env
+source env/bin/activate
+
+# Clone the repository and install the development dependencies
+git clone https://github.com/NPLinker/nplinker.git
+cd nplinker
+pip install -e ".[dev]"
+install-nplinker-deps
+```
+
+#### Unit tests
+
+To run the unit tests, you can use the following command:
+
+```shell
+pytest
+```
+Pytest will use all available CPU cores to run the unit tests in parallel.
+
+#### Integration tests
+
+To run the integration tests, you can use the following command:
+
+```shell
+pytest -n1 tests/integration
+```
+The `-n1` is to use one CPU core to run the tests. Change it to `-n2` if you want to use two CPU cores to run in parallel.
+
 ### Usage
 
 See the [documentation](https://nplinker.github.io/nplinker) for more information about how to use NPLinker.

diff --git a/docs/index.md b/docs/index.md
@@ -7,5 +7,5 @@ For a deep understanding of NPLinker, please refer to the [original paper](https
 
 !!! warning "Under Development"
 
-    NPLinker v2 is under active development. The documentation is not complete yet. If you have any 
-    questions, please contact us via [GitHub Issues](https://github.com/NPLinker/nplinker/issues)
+    NPLinker v2 is under active development ([see its pre-releases](https://pypi.org/project/nplinker/#history)). 
+    The documentation is not complete yet. If you have any questions, please contact us via [GitHub Issues](https://github.com/NPLinker/nplinker/issues).
diff --git a/docs/install.md b/docs/install.md
@@ -5,7 +5,9 @@
     - Python version ≥3.9
 
 
-NPLinker is a python package that has both pypi packages and non-pypi packages as dependencies.
+NPLinker is a python package that has both pypi packages and non-pypi packages as dependencies. It 
+requires <span style="color:red;">**~4.5GB**</span> of disk space to install all the dependencies. 
+
 Install `nplinker` package as following:
 
 
@@ -17,14 +19,15 @@ python --version
 python -m venv env          # (1)!
 source env/bin/activate
 
-# install nplinker package
-pip install nplinker
+# install nplinker package (requiring ~300MB of disk space)
+pip install nplinker==2.0.0a1 # (2)! 
 
-# install nplinker non-pypi dependencies and databases
+# install nplinker non-pypi dependencies and databases (~4GB)
 install-nplinker-deps
 ```
 
 1. A virtual environment is ***required*** to install the the non-pypi dependencies. You can also use `conda` to create a new environment. But NPLinker is not available on conda yet.
+2. NPLinker v2 is still under development and released as [pre-release](https://pypi.org/project/nplinker/#history). To install the pre-release, you have to explicitly specifiy the version. The command `pip install nplinker` will install the legacy NPLinker (v1.3.2), which is not recommended. 
 
 ## Install from source code
 

diff --git a/docs/logging.md b/docs/logging.md
@@ -0,0 +1,50 @@
+NPLinker uses the standard library [logging](https://docs.python.org/3/library/logging.html#module-logging) 
+module for managing log messages and the python library [rich](https://rich.readthedocs.io/en/latest/logging.html) 
+to colorize the log messages. Depending on how you use NPLinker, you can set up logging in different ways.
+
+## NPLinker as an application
+If you're using NPLinker as an application, you're running the whole workflow of NPLinker as 
+described in the [Quickstart](./quickstart.md). In this case, you can set up logging in the nplinker 
+configuration file `nplinker.toml`. 
+
+## NPLinker as a library
+If you're using NPLinker as a library, you're using only some functions and classes of NPLinker in 
+your script. By default, NPLinker will not log any messages. However, you can set up logging in your
+script to log messages. 
+
+```python title="Set up logging in 'your_script.py'"
+# Set up logging configuration first
+from nplinker import setup_logging
+
+setup_logging(level="DEBUG", file="nplinker.log", use_console=True) # (1)!
+
+# Your business code here
+# e.g. download and extract nplinker example data
+from nplinker.utils import download_and_extract_archive
+
+download_and_extract_archive(
+    url="https://zenodo.org/records/10822604/files/nplinker_local_mode_example.zip",
+    download_root=".",
+)
+```
+
+1. The `setup_logging` function sets up the logging configuration. The `level` argument sets the 
+   logging level. The `file` argument sets the log file. The `use_console` argument sets whether to 
+   log messages to the console.
+
+
+The log messages will be written to the log file `nplinker.log` and displayed in the console with a 
+format like this: `[Date Time] Level Log-message Module:Line`.
+
+```shell title="Run your script in a terminal"
+# Run your script
+$ python your_script.py
+Downloading nplinker_local_mode_example.zip ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100.0% • 195.3/195.3 MB • 2.6 MB/s • 0:00:00 • 0:01:02 # (1)!
+[2024-05-10 15:14:48] INFO     Extracting nplinker_local_mode_example.zip to .                      utils.py:401
+
+# Check the log file
+$ cat nplinker.log
+[2024-05-10 15:14:48] INFO     Extracting nplinker_local_mode_example.zip to .                      utils.py:401
+```
+
+1. This is a progress bar but not a log message.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -51,6 +51,7 @@ nav:
   - Welcome to NPLinker: index.md
   - Installation: install.md
   - Quickstart: quickstart.md
+  - Logging: logging.md
   # - Configuration: config.md
   # - NPLinker Architecture: architecture.md
   # - Arranger pipeline: arranger.md