Merge pull request #118 from Roestlab/update/docs

Update/docs

README.md

@@ -57,6 +57,10 @@ pip install -e .
 
 </details>
 
+<br>
+
+For detailed OS-specific (Windows, MacOS, Ubuntu) installation guides, please refer to the [documentation](https://massdash.readthedocs.io/en/latest/Installation.html).
+
 ## Quick start
 
 Launch MassDash by typing the following command in your terminal:
@@ -140,6 +144,10 @@ docker run -p 8501:8501 singjust/massdash:latest
 
 **Note:** The MassDash Docker image binds to port 8501 when running MassDash locally.
 
+## Documentation
+
+For more information (API and tutorial walk-throughs), please refer to the [documentation](https://massdash.readthedocs.io/en/latest/index.html).
+
 ## Contribute
 
 * [Issues Tracker](https://github.com/Roestlab/massdash/issues)

docs/Installation.rst

@@ -1,6 +1,8 @@
 Installation
 ============
 
+
+
 The Python Package Index
 ------------------------
 
@@ -13,7 +15,7 @@ MassDash is available as a python package on the python package index, and can b
 Building from Source
 --------------------
 
-The source code is freely open and accessible on Github at https://github.com/Roestlab/massdash under the `BSD-3-Cluase license <https://github.com/Roestlab/massdash?tab=BSD-3-Clause-1-ov-file>`. The package can be installed by cloning and installing from source using pip.
+The source code is freely open and accessible on Github at https://github.com/Roestlab/massdash under the `BSD-3-Clause license <https://github.com/Roestlab/massdash?tab=BSD-3-Clause-1-ov-file>`_. The package can be installed by cloning and installing from source using pip.
 
 First clone the repository:
 
@@ -42,3 +44,17 @@ MassDash is available as a docker image on dockerhub `here <https://github.com/R
 
         docker pull ghcr.io/roestlab/massdash:latest 
 
+Installation Guides
+-------------------
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   installation_docs/windows_installation
+   installation_docs/macos_installation
+   installation_docs/ubuntu_installation
+
+1. :doc:`Windows Installation <installation_docs/windows_installation>` - Installation guide for Windows
+2. :doc:`Mac Installation <installation_docs/macos_installation>` - Installation guide for Mac BigSur
+3. :doc:`Ubuntu Installation <installation_docs/ubuntu_installation>` - Installation guide for Ubuntu

docs/README.md

@@ -0,0 +1,25 @@
+# MassDash Documentation
+
+*** 
+
+Documentation for the MassDash project is built using [sphinx](https://www.sphinx-doc.org/en/master/) and is hosted on Read the Docs [MassDash](https://massdash.readthedocs.io/en/latest/).
+
+## Building the Documentation
+
+To build the documentation locally, you will need to install the following dependencies in requirements.txt:
+
+```bash
+pip -r requirements.txt
+```
+
+Then you can build the documentation using the following command (assuming you are in the docs directory):
+
+```bash
+sphinx-build -b html ./source ./build
+```
+
+This will build the documentation in the build directory. You can then open the *./build/html/index.html* file in your browser to view the documentation.
+
+## Adding Documentation
+
+To add documentation, you will need to add a new **.rst** file in this docs directory. You can then add the file to the *index.rst* file to include it in the documentation.

docs/conf.py

@@ -33,7 +33,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.napoleon', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'nbsphinx', 'sphinx.ext.autosectionlabel', 'sphinx_copybutton' ]
+extensions = ['sphinx.ext.napoleon', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'nbsphinx', 'sphinx.ext.autosectionlabel', 'sphinx_copybutton']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/installation_docs/macos_installation.rst

@@ -0,0 +1,83 @@
+MassDash Installation on MacOS Big Sur
+======================================
+
+This guide will help you install MassDash on MacOS Big Sur.
+
+.. note::
+    This tutorial was created using a clean installation of MacOS Big Sur using a virtual machine. The virtual machine was created using Oracle VM VirtualBox, with 32Gb of RAM, 8 processors, and 64Gb of storage. The virtual machine was created using the macOS Big Sur iso file from `The Internet Archive <https://archive.org/details/mac-osx-big-sur-iso>`_.
+
+Prerequisites
+-------------
+
+It is recommended to use Anaconda to manage Python environments and packages. You can download Anaconda from `here <https://www.anaconda.com/download>`_. You can find documentation for installing Anaconda on MacOS `here <https://docs.anaconda.com/free/anaconda/install/mac-os/>`__.
+
+Installation
+------------
+
+1. Launch a terminal and create a new conda environment using the following command:
+
+   .. code-block:: bash
+
+      conda create -n massdash python=3.9 -y
+
+.. image:: ./assets/img/macos_conda_create_env.png
+   :alt: Create a new conda environment
+   :align: center
+
+2. Activate the new conda environment using the following command:
+
+    .. code-block:: bash
+    
+        conda activate massdash
+
+.. image:: ./assets/img/macos_conda_env_activate.png
+    :alt: Activate the new conda environment
+    :align: center
+
+3. Install massdash using the following command:
+
+    .. code-block:: bash
+
+        pip install massdash
+
+.. image:: ./assets/img/macos_massdash_install.png
+    :alt: Install massdash
+    :align: center
+
+Usage
+-----
+
+Help
+~~~~
+
+You can get help on how to use MassDash's GUI by running the following command in the terminal:
+
+.. code-block:: bash
+
+    massdash gui --help
+
+.. image:: ./assets/img/macos_conda_cmd_massdash_gui_help.png
+
+Launch MassDash GUI
+~~~~~~~~~~~~~~~~~~~
+
+You can launch MassDash's GUI by running the following command in the terminal:
+
+.. code-block:: bash
+
+    massdash gui
+
+A browser window will open with the MassDash GUI. If the browser window does not open, you can navigate to the following URL in your browser using the local url provided in the Anaconda CMD.exe output, by default it should be `http://localhost:8501/`, unless the port is changed.
+
+.. note::
+    It is recommended to use Google Chrome or Firefox to open the MassDash GUI instead of Safari.
+
+.. note::
+    MassDash warns you that onnxruntime, torch, and torchmeets are not installed. You can ignore this warning if you do not plan to use the MassDash's peak picking conformer model. 
+
+.. image:: ./assets/img/macos_conda_cmd_massdash_gui_run.png
+
+Once the browser window opens, you can start using MassDash's GUI to visualize your mass spectrometry data. For more information on the GUI, please refer to the `MassDash GUI Documentation <../GUI.rst>`_.
+
+.. image:: ./assets/img/macos_massdash_gui.png
+.. image:: ./assets/img/macos_massdash_gui_example.png

docs/installation_docs/ubuntu_installation.rst

@@ -0,0 +1,80 @@
+MassDash Installation on Ubuntu 22.04
+======================================
+
+This guide will help you install MassDash on Ubuntu 22.04.
+
+.. note::
+    This tutorial was created using a clean installation of Ubuntu 22.04 using a virtual machine. The virtual machine was created using Oracle VM VirtualBox, with 64Gb of RAM, 8 processors, and 64Gb of storage. The virtual machine was created using the Ubuntu 22.04 iso file from `Ubuntu <https://ubuntu.com/download/desktop/thank-you?version=22.04.4&architecture=amd64>`_.
+
+Prerequisites
+-------------
+
+It is recommended to use Anaconda to manage Python environments and packages. You can download Anaconda from `here <https://www.anaconda.com/download>`_. You can find documentation for installing Anaconda on Ubuntu `here <https://docs.anaconda.com/free/anaconda/install/linux/>`__.
+
+Installation
+------------
+
+1. Launch a terminal and create a new conda environment using the following command:
+
+   .. code-block:: bash
+
+      conda create -n massdash python=3.9 -y
+
+.. image:: ./assets/img/ubuntu_conda_env_create.png
+   :alt: Create a new conda environment
+   :align: center
+
+2. Activate the new conda environment using the following command:
+
+    .. code-block:: bash
+    
+        conda activate massdash
+
+.. image:: ./assets/img/ubuntu_conda_env_activate.png
+    :alt: Activate the new conda environment
+    :align: center
+
+3. Install massdash using the following command:
+
+    .. code-block:: bash
+
+        pip install massdash
+
+.. image:: ./assets/img/ubuntu_massdash_install.png
+    :alt: Install massdash
+    :align: center
+
+Usage
+-----
+
+Help
+~~~~
+
+You can get help on how to use MassDash's GUI by running the following command in the terminal:
+
+.. code-block:: bash
+
+    massdash gui --help
+
+.. image:: ./assets/img/ubuntu_conda_cmd_massdash_gui_help.png
+
+Launch MassDash GUI
+~~~~~~~~~~~~~~~~~~~
+
+You can launch MassDash's GUI by running the following command in the terminal:
+
+.. code-block:: bash
+
+    massdash gui
+
+A browser window will open with the MassDash GUI. If the browser window does not open, you can navigate to the following URL in your browser using the local url provided in the Anaconda CMD.exe output, by default it should be `http://localhost:8501/`, unless the port is changed.
+
+.. note::
+    MassDash warns you that onnxruntime, torch, and torchmeets are not installed. You can ignore this warning if you do not plan to use the MassDash's peak picking conformer model. 
+
+.. image:: ./assets/img/ubuntu_conda_cmd_massdash_gui_run.png
+
+Once the browser window opens, you can start using MassDash's GUI to visualize your mass spectrometry data. For more information on the GUI, please refer to the `MassDash GUI Documentation <../GUI.rst>`_.
+
+.. image:: ./assets/img/ubuntu_massdash_gui.png
+.. image:: ./assets/img/ubuntu_massdash_gui_example.png

docs/installation_docs/windows_installation.rst

@@ -0,0 +1,80 @@
+MassDash Installation on Windows 10
+====================================
+
+This guide will walk you through the installation of MassDash on a Windows 10 machine.
+
+.. note::
+    This tutorial was created using a clean installation of Windows 10 using a virtual machine. The virtual machine was created using Oracle VM VirtualBox, with 50Gb of RAM, 8 processors, and 50Gb of storage. The virtual machine was created using the Windows 10 ISO file from `Microsoft <https://www.microsoft.com/en-us/software-download/windows10>`_.
+
+Prerequisites
+-------------
+
+It is recommended to use Anaconda to manage Python environments and packages. You can download Anaconda from `here <https://www.anaconda.com/download>`_. You can find documentation for installing Anaconda on windows `here <https://docs.anaconda.com/free/anaconda/install/windows/>`__.
+
+Installation
+------------
+
+1. Launch the Anaconda Navigator from the start menu.
+
+2. Launch the Anaconda CMD.exe Prompt from the Anaconda Navigator.
+
+.. image:: ./assets/img/windows_anaconda_nav_cmd_prompt_launch.png
+
+3. Create a new environment by running the following command in the Anaconda CMD.exe Prompt:
+
+.. code-block:: bash
+
+    conda create -n massdash python=3.9 -y
+
+.. image:: ./assets/img/windows_conda_cmd_prompt_create_env.png
+
+4. Activate the new environment by running the following command in the Anaconda CMD.exe Prompt:
+
+.. code-block:: bash
+
+    conda activate massdash
+
+.. image:: ./assets/img/windows_conda_cmd_activate_env.png
+
+5. Install MassDash by running the following command in the Anaconda CMD.exe Prompt:
+
+.. code-block:: bash
+
+    pip install massdash
+
+.. image:: ./assets/img/windows_conda_cmd_install_massdash.png
+
+Usage
+-----
+
+Help
+~~~~
+
+You can get help on how to use MassDash's GUI by running the following command in the Anaconda CMD.exe Prompt:
+
+.. code-block:: bash
+
+    massdash gui --help
+
+.. image:: ./assets/img/windows_conda_cmd_massdash_gui_help.png
+
+Launch MassDash GUI
+~~~~~~~~~~~~~~~~~~~
+
+You can launch MassDash's GUI by running the following command in the Anaconda CMD.exe Prompt:
+
+.. code-block:: bash
+
+    massdash gui
+
+A browser window will open with the MassDash GUI. If the browser window does not open, you can navigate to the following URL in your browser using the local url provided in the Anaconda CMD.exe output, by default it should be `http://localhost:8501/`, unless the port is changed.
+
+.. note::
+    MassDash warns you that onnxruntime, torch, and torchmeets are not installed. You can ignore this warning if you do not plan to use the MassDash's peak picking conformer model. 
+
+.. image:: ./assets/img/windows_conda_cmd_massdash_gui_run.png
+
+Once the browser window opens, you can start using MassDash's GUI to visualize your mass spectrometry data. For more information on the GUI, please refer to the `MassDash GUI Documentation <../GUI.rst>`_.
+
+.. image:: ./assets/img/windows_massdash_gui.png
+.. image:: ./assets/img/windows_massdash_gui_example.png