PyOpenSci REVIEW - add setup to docs, add building docs to contributing

CONTRIBUTING.md

@@ -74,6 +74,16 @@ Alternatively, you can directly work on a developer environment in the browser w
 __Known issues__:
 Port forwarding within the codespace doesn't work very well for Streamlit (pynteny app). This is a [known issue](https://discuss.streamlit.io/t/how-to-make-streamlit-run-on-codespaces/24526) regarding Streamlit and Codespaces.
 
+## Building the documentation
+
+The documentation is formed by a series of markdown files located in directory [docs](https://github.com/Robaina/Pynteny/tree/main/docs). This repo uses [mkdocs](https://www.mkdocs.org/) to automatically generate documentation pages from markdown files. Also, [MathJax](https://github.com/mathjax/MathJax) syntax is allowed!
+
+This means that, to modify the [API reference](https://robaina.github.io/Pynteny/references/api/), all you need to do is to modify the docstring directly in the source file where the definion/class is located. And, to update the documentation pages, you just have to update the corresponding markdown file in the [docs](https://github.com/Robaina/Pynteny/tree/main/docs) directory. Note that, if you need to change the documentation structure (e.g., add or new pages),you would need to tell mkdocs about this change through its [configuration file](https://github.com/Robaina/Pynteny/blob/main/mkdocs.yml). Or just open an issue and ask for help!
+
+When all the changes are ready to deploy, just open a pull request. After reviewing and merging the changes, the documentation will be automatically deployed.
+Run the documentation locally with:
+
+> mkdocs serve
 ## Tests on push and pull request to main
 
 Pynteny's repo contains a [GitHub Action](https://github.com/features/actions) to perform build and integration tests which is triggered automatically on push and pull request events to the main brach. Currently the tests include building and installing Pynteny in Ubuntu and MacOS and running the [test](tests) suit.

README.md

@@ -115,6 +115,7 @@ Here are some Jupyter Notebooks with examples to show how Pynteny works:
 <a href="https://colab.research.google.com/github/Robaina/Pynteny/blob/main/docs/examples/example_api_colab.ipynb" target="_blank"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/></a>
 * [Pynteny API](https://robaina.github.io/Pynteny/examples/example_api/)
 * [Pynteny CLI](https://robaina.github.io/Pynteny/examples/example_cli/)
+* [Sus operon](https://robaina.github.io/Pynteny/examples/example_sus/)
 
 You can find more notebooks in the [examples directory](docs/examples/). We invite you to explore Pynteny's web application by executing the command `pynteny app`. Find more info in the [documentation](https://robaina.github.io/Pynteny/).
 

docs/index.md

@@ -10,6 +10,31 @@ These are the available subcommands, run as ```pynteny <subcommand> <options>```
 - [parse](subcommands/parse.md)
 - [app](subcommands/app.md)
 
+## Setup
+
+Install with conda:
+
+1. Create dedicated conda environment (highly recommended)
+
+```bash
+conda create -n pynteny
+conda activate pynteny
+```
+2. Install pynteny
+
+```bash
+conda install -c bioconda pynteny
+```
+
+3. Check that installation worked fine:
+
+```bash
+pynteny --help
+```
+### Installing Pynteny on Windows
+
+Pynteny is designed to run on Linux machines. However, it can be installed within the [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) via conda.
+
 ## General usage
 
 Pynteny's main subcommand, [`pynteny search`](subcommands/search.md), requires a peptide (ORF) sequence database in fasta format in which record labels contain positional information of each sequence with respect to their contig of origin. Additionally, labels must follow the following format:
@@ -28,9 +53,21 @@ $>HMM_a \:\: n_{ab} \:\: > (HMM_{b1} | HMM_{b2}) \:\: n_{bc} \:\: < HMM_c.$
 
 Where $HMM_a$ represents the name of the HMM to be used (corresponding to the file name without the extension), $n_{ab}$ is an integer representing the maximum number of genes between HMMs a and b, < and > indicate the strand in which to search for the HMM pattern, antisense and sense, respectively. Note that more than one HMM can be employed for a single gene in the structure, as indicated by the HMM group $(HMM_{b1} | HMM_{b2})$ above. In these cases, [`pynteny search`](subcommands/search.md) will search for sequences that matched any HMM contained within the HMM group.
 
-## Examples
+## Getting started and Examples
+
+Here are some Jupyter Notebooks with examples to show how Pynteny works.
+
+<a href="https://colab.research.google.com/github/Robaina/Pynteny/blob/main/docs/examples/example_api_colab.ipynb" target="_blank"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/></a>
+* [Pynteny API](https://robaina.github.io/Pynteny/examples/example_api/)
+* [Pynteny CLI](https://robaina.github.io/Pynteny/examples/example_cli/)
+* [Sus operon](https://robaina.github.io/Pynteny/examples/example_sus/)
+
+You can find more notebooks in the [examples directory](docs/examples/). We invite you to explore Pynteny's web application by executing the command `pynteny app`. Find more info in the [documentation](https://robaina.github.io/Pynteny/).
+
+## Contributing
+
+Contributions are always welcome! If you don't know where to start, you may find an interesting [issue to work in here](https://github.com/Robaina/Pynteny/issues). Please, read our [contribution guidelines](https://github.com/Robaina/Pynteny/blob/main/CONTRIBUTING.md) first.
 
-There are some Jupyter notebooks with examples of how to use Pynteny's command-line interface as well as its Python API. Check them out here in the examples section or in the [GitHub repo](https://github.com/Robaina/Pynteny/tree/master/docs/examples).
 ## Citation
 
 If you use this software, please cite it as below:

envs/pynteny-dev.yml

@@ -18,4 +18,10 @@ dependencies:
   - psutil >= 5.9
   - python-wget 
   - streamlit=1.16
-  - streamlit-aggrid
+  - streamlit-aggrid
+  - pip:
+    - mkdocs
+    - mkdocs-gen-files
+    - pymdown-extensions
+    - mkdocs-jupyter
+    - mkdocstrings[python]