improve docstrings (#266)

* add new options to mkdocs config

* change order of APIs

* use list to display docstring parameters

* update options for docstring python handler

* Update nplinker.md

* use uniformed base path for snippets

* update schemas

- move code from `utils.py` to `__init__.py`
- add docstring to module attributes
- add schema content to docstring

* update docstrings

* use pip `--pre` option to install pre-release

* remove legacy test to avoid numpy error

* remove trailing whitespace

README.md

@@ -41,7 +41,7 @@ python -m venv env
 source env/bin/activate
 
 # install from nplinker releases (requiring ~300MB of disk space)
-pip install nplinker==2.0.0a2
+pip install --pre nplinker
 
 # or install the latest from source code
 pip install git+https://github.com/nplinker/nplinker@dev 

docs/api/nplinker.md

@@ -1,3 +1,8 @@
 ::: nplinker
+    options:
+        members:
+            - NPLinker
+            - setup_logging
+
 ::: nplinker.defaults
 ::: nplinker.config

docs/concepts/config_file.md

@@ -1,15 +1,15 @@
 ## Configuration Template
 
 ```toml
---8<-- "nplinker.toml"
+--8<-- "src/nplinker/data/nplinker.toml"
 ```
 
 
 ## Default Configurations
 The default configurations are automatically used by NPLinker if you don't set them in your config file.
 
 ```toml
---8<-- "nplinker_default.toml"
+--8<-- "src/nplinker/nplinker_default.toml"
 ```
 
 ## Config loader

docs/concepts/gnps_data.md

@@ -1,3 +1,5 @@
+# GNPS data 
+
 NPLinker requires GNPS molecular networking data as input. It currently accepts data from the following 
 GNPS workflows:
 

docs/install.md

@@ -16,17 +16,18 @@ python --version
 
 # Create a new virtual environment
 python -m venv env          # (1)!
-source env/bin/activate
+source env/bin/activate     # (2)! 
 
 # install nplinker package (requiring ~300MB of disk space)
-pip install nplinker==2.0.0a2 # (2)! 
+pip install --pre nplinker # (3)!
 
 # 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. 
+2. Check `pip` command and make sure it is provided by the activated virtual environment. 
+3. NPLinker v2 is still under development and released as [pre-release](https://pypi.org/project/nplinker/#history). To install the pre-release, you need the `--pre` option. 
 
 ## Install from source code
 

docs/logging.md

@@ -1,3 +1,4 @@
+# How to setup logging
 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.

mkdocs.yml

@@ -27,6 +27,10 @@ theme:
     - content.code.copy
     - announce.dismiss
     - navigation.tabs
+    - navigation.sections
+    - navigation.top
+    - search.highlight
+    - search.suggest
   icon:
     logo: 'material/library-outline'
     previous: fontawesome/solid/angle-left
@@ -65,9 +69,12 @@ nav:
   - Dataset Arranger: diagrams/arranger.md
   - Dataset Loader: diagrams/loader.md
 - API Documentation:
-  - NPLinker: api/nplinker.md
-  - Dataset Arranger: api/arranger.md
-  - Dataset Loader: api/loader.md
+  - NPLinker Core:
+    - NPLinker: api/nplinker.md
+    - Dataset Arranger: api/arranger.md
+    - Dataset Loader: api/loader.md
+    - Schemas: api/schema.md
+    - Utilities: api/utils.md
   - Genomics Data:
     - Abstract Base Classes: api/genomics_abc.md
     - Data Models: api/genomics.md
@@ -88,8 +95,6 @@ nav:
     - Scoring Methods: api/scoring_methods.md
     - Data Models: api/scoring.md
     - Utilities: api/scoring_utils.md
-  - Schemas: api/schema.md
-  - General Utilities: api/utils.md
 
 markdown_extensions:
 # https://python-markdown.github.io/extensions/
@@ -110,8 +115,9 @@ markdown_extensions:
 - pymdownx.tabbed:
     alternate_style: true
 - pymdownx.magiclink
-- pymdownx.snippets: # use files outside of docs folder 
-    base_path: [., ./src/nplinker, ./src/nplinker/data]
+- pymdownx.keys
+- pymdownx.snippets: # use files outside of docs folder, syntax is `--8<-- "path/to/file"`
+    base_path: [.]
 
 watch:
 - docs
@@ -121,29 +127,36 @@ plugins:
     alias_type: symlink
     canonical_version: latest
 - search
+- autorefs # https://mkdocstrings.github.io/usage/#cross-references-to-any-markdown-heading
 - exclude:
     glob:
     - __pycache__/*
 - mkdocstrings:
     handlers:
       python:
+        # https://mkdocstrings.github.io/python/usage/#configuration
         paths: [src]
         import:
           - https://docs.python.org/3/objects.inv
           - https://numpy.org/doc/stable/objects.inv
           - https://docs.scipy.org/doc/scipy/objects.inv
           - https://pandas.pydata.org/docs/objects.inv
         options:
+          # NOTE: some options are not available for free, e.g. `show_inheritance_diagram` and `summary`. 
+          # Members options
           members_order: source
-          filters: ["!^_"]
+          filters: ["!^_[^_]", "!^__all__$", "!^logger$"] # exclude private objects, "__all__" and "logger" 
+          # Docstrings options
+          docstring_section_style: list
           docstring_options:
             ignore_init_summary: true
           merge_init_into_class: true
           show_if_no_docstring: true
-          show_root_heading: true
-          show_root_full_path: false
+          # Signatures/annotations options
           show_signature_annotations: true
           signature_crossrefs: true
           separate_signature: true
+          # Headings options
+          show_root_heading: true
           show_symbol_type_heading: true
           show_symbol_type_toc: true