doc: README with the documentation links and the logo for dark mode

README.md

@@ -1,41 +1,45 @@
-<img src="img/RAVEN.png" width="200px">
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="img/raven-logo-white.png">
+  <img src="img/raven-logo.png" alt="RAVEN" width="400px">
+</picture>
 
-[![Current release](https://img.shields.io/github/release/CompMetEng/RAVEN/all.svg)](https://github.com/CompMetEng/RAVEN/releases/)
+[![Release](https://img.shields.io/github/v/release/CompMetEng/RAVEN?include_prereleases)](https://github.com/CompMetEng/RAVEN/releases/)
+[![Documentation](https://readthedocs.org/projects/raven-docs/badge/?version=latest)](https://raven-docs.readthedocs.io/en/latest/)
 [![GitHub Discussions](https://img.shields.io/github/discussions-search?query=repo%3ACompMetEng%2FRAVEN&label=GitHub%20Discussions)](https://github.com/CompMetEng/RAVEN/discussions)
 [![Zenodo](https://zenodo.org/badge/DOI/10.5281/zenodo.3689518.svg)](https://doi.org/10.5281/zenodo.3689518)
-[![MATLAB File Exchange](https://www.mathworks.com/matlabcentral/images/matlab-file-exchange.svg)](https://se.mathworks.com/matlabcentral/fileexchange/112330-raven-toolbox)
+
+**[Documentation](https://raven-docs.readthedocs.io/en/latest/)** · [Installation](https://raven-docs.readthedocs.io/en/latest/installation/index.html) · [Guide](https://raven-docs.readthedocs.io/en/latest/guide/index.html) · [API reference](https://raven-docs.readthedocs.io/en/latest/api/index.html) · [Migrate from RAVEN 2](https://raven-docs.readthedocs.io/en/latest/migrate.html) · [Citations](https://raven-docs.readthedocs.io/en/latest/references.html)
 
 ## About RAVEN
 
-The **RAVEN** (Reconstruction, Analysis and Visualization of Metabolic Networks) Toolbox is a software suite for MATLAB that allows for semi-automated reconstruction of genome-scale models (GEMs). It makes use of published models and/or the KEGG database, coupled with extensive gap-filling and quality control features. The software suite also contains methods for visualizing simulation results and omics data, as well as a range of methods for performing simulations and analyzing the results. The software is a useful tool for system-wide data analysis in a metabolic context and for streamlined reconstruction of metabolic networks based on protein homology.
+The **RAVEN** (Reconstruction, Analysis and Visualization of Metabolic Networks) Toolbox is a software suite for MATLAB for the semi-automated reconstruction of genome-scale metabolic models (GEMs). It reconstructs from published models or from the KEGG database, with gap-filling and quality control, and it simulates and analyses models and visualises simulation results and omics data. For context-specific model extraction, `ftINIT` is the method to use; `getINITModel` and `runINIT` are the original tINIT implementation, kept to reproduce models built with it.
+
+RAVEN has a Python port, [raven-toolbox](https://github.com/CompMetEng/raven-toolbox), built on [cobrapy](https://github.com/opencobra/cobrapy). The documentation covers both toolboxes, and [RAVEN 3 and raven-toolbox](https://raven-docs.readthedocs.io/en/latest/raven3-vs-raven-toolbox.html) lists the functions that exist in one of them and the functions that return a different result in each.
 
-The latest stable release is **RAVEN 2.11.4**, maintained in [SysBioChalmers/RAVEN](https://github.com/SysBioChalmers/RAVEN).
+This repository is where RAVEN 3 is developed. RAVEN 3 is a breaking release: the code is reorganised into functional folders, optional function arguments are passed by position, by name or both, external binaries and KEGG reference data are fetched on demand, several MATLAB toolbox dependencies are dropped, and low-value and duplicate functions are removed. The code can change until 3.0.0 is tagged. The last RAVEN 2 release is 2.11.4, maintained in [SysBioChalmers/RAVEN](https://github.com/SysBioChalmers/RAVEN). [Migrating from RAVEN 2](https://raven-docs.readthedocs.io/en/latest/migrate.html) lists every change for users who upgrade.
 
-> **This repository is where RAVEN 3 is under active development**, with the upcoming **3.0.0b1** beta as its first release, targeting a final **3.0.0**. RAVEN 3 is a deliberate breaking release: the codebase has been reorganized into functional folders, optional function arguments can now be passed positionally, by name, or both, external binaries and KEGG reference data are fetched on demand instead of bundled in the repository, several MATLAB toolbox dependencies were dropped, and a number of low-value or duplicate functions were removed alongside new capabilities. Until 3.0.0 is tagged, the code can still change. See the [migration guide](#documentation) for the full list of changes for users upgrading from RAVEN 2.
+## Get started
 
-For context-specific model extraction, use `ftINIT`; `getINITModel` and `runINIT` are the original tINIT implementation, kept for reproducing models built with it.
+1. Install RAVEN as described in the [installation instructions](https://raven-docs.readthedocs.io/en/latest/installation/raven.html). The Add-Ons manager of MATLAB installs the latest stable release, which is RAVEN 2; a RAVEN 3 pre-release is installed from this repository, and the instructions describe how. `checkRaven` verifies the installation and the solver.
+2. Follow [Getting started](https://raven-docs.readthedocs.io/en/latest/guide/getting-started.html) in the guide, which has MATLAB and Python examples side by side, or open a script in the [`tutorials`](https://github.com/CompMetEng/RAVEN/tree/develop/tutorials) folder. The tutorials come from the original RAVEN paper and are described in [Legacy tutorials](https://raven-docs.readthedocs.io/en/latest/tutorials/index.html).
+3. The [GEM reconstruction protocol](https://raven-docs.readthedocs.io/en/latest/protocol/index.html) reconstructs a model for *Hansenula polymorpha* from start to finish.
 
+## Documentation and support
 
-## Documentation
-Installation instructions, a user guide and the API reference are published at [raven-docs](https://raven-docs.readthedocs.io/en/latest/).
+The installation instructions, the guide, the protocol, the tuned parameter defaults and the API reference for MATLAB and Python are at [raven-docs](https://raven-docs.readthedocs.io/en/latest/). The function help texts in this repository generate the MATLAB part of the API reference. Use [GitHub Discussions](https://github.com/CompMetEng/RAVEN/discussions) for questions and comments, and [issues](https://github.com/CompMetEng/RAVEN/issues) for bug reports.
 
-Full user documentation, including a migration guide for users upgrading from RAVEN 2 to RAVEN 3, is published at [raven-docs](https://raven-docs.readthedocs.io/en/latest/).
+## Cite us
 
+If you use RAVEN in your work, please cite:
 
-## Cite Us
-If you use RAVEN in your scientific work, please cite:
 > Wang H, Marcišauskas S, Sánchez BJ, Domenzain I, Hermansson D, Agren R, Nielsen J, Kerkhoven EJ. (2018) RAVEN 2.0: A versatile toolbox for metabolic network reconstruction and a case study on _Streptomyces coelicolor_. PLoS Comput Biol 14(10): e1006541. doi:[10.1371/journal.pcbi.1006541](https://doi.org/10.1371/journal.pcbi.1006541).
 
-All releases are also archived in [Zenodo](https://doi.org/10.5281/zenodo.3689518), so you can cite the specific version of RAVEN used in your study
+All releases are archived on [Zenodo](https://doi.org/10.5281/zenodo.3689518), which allows citing the version used. If you use ftINIT, please also cite:
 
-If you use ftINIT in your scientific work, please cite:
 > Gustafsson J, Anton M, Roshanzamir F, Jörnsten R, Kerkhoven EJ, Robinson JL, Nielsen J. (2023) Generation and analysis of context-specific genome-scale metabolic models derived from single-cell RNA-Seq data. Proc Natl Acad Sci 120(6): e2217868120. doi:[10.1073/pnas.2217868120](https://doi.org/10.1073/pnas.2217868120)
 
-For crediting supporting work, please cite doi:[10.1002/msb.145122](http://msb.embopress.org/content/10/3/721) (`tInit`); doi:[10.1371/journal.pcbi.1000859](http://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1000859) (`randomsampling`). For crediting RAVEN 1, cite doi:[10.1371/journal.pcbi.1002980](http://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1002980). For more details, see [wiki#cite-us](https://github.com/SysBioChalmers/RAVEN/wiki#cite-us).
-
-## Contact Us
-Use [GitHub Discussions](https://github.com/CompMetEng/RAVEN/discussions) for support, to ask questions or leave comments.
+[Citations](https://raven-docs.readthedocs.io/en/latest/references.html) lists the papers behind individual methods, among them the first RAVEN paper (2013), random sampling and the INIT method.
 
 ## Contributing
 
-Contributions are always welcome! Please read the [Contributor guidelines](https://github.com/CompMetEng/RAVEN/blob/develop/.github/CONTRIBUTING.md) to get started. RAVEN 3 development happens on the `develop` branch of this repository; RAVEN 2.x is maintained in [SysBioChalmers/RAVEN](https://github.com/SysBioChalmers/RAVEN).
+Contributions are welcome. Read the [contributing guidelines](https://github.com/CompMetEng/RAVEN/blob/develop/.github/CONTRIBUTING.md) first. RAVEN 3 is developed on the `develop` branch, and RAVEN 2 is maintained in [SysBioChalmers/RAVEN](https://github.com/SysBioChalmers/RAVEN).

_config.yml

@@ -1,4 +1,4 @@
 theme: jekyll-theme-minimal
-logo: img/RAVEN.png
+logo: img/raven-logo.png
 show_downloads: true
 keep_files: ["docs/html/"]