Merge pull request #1108 from slaclab/doc-update-tutorials

Update Documentation, Tutorials, Docstrings, add Typehints

Author: ruck314

docs/src/conf.py

@@ -42,6 +42,7 @@
     'sphinx.ext.viewcode',
     'sphinx.ext.githubpages',
     'sphinx.ext.napoleon',
+    'sphinx_copybutton',
     'breathe']
 
 # Add any paths that contain templates here, relative to this directory.
@@ -128,6 +129,12 @@
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'Roguedoc'
 
+# -- Options for Sphinx Rendering -----------------------------------------
+# Sets typehints in both signature and description.
+autodoc_typehints = 'both'
+# Change class attribute rendering style
+napoleon_use_ivar = True
+
 
 # -- Options for LaTeX output ---------------------------------------------
 
@@ -185,4 +192,3 @@
 # Breath configuration
 breathe_projects = { 'rogue' : '../build/doxyxml' }
 breathe_default_project = 'rogue'
-

docs/src/index.rst

@@ -7,13 +7,20 @@
 Welcome to Rogue's documentation!
 =================================
 
+Rogue is a SLAC Python Based Hardware Abstraction and Data Acquisition System. Look at our :ref:`Introduction` page for information about Rogue.
+
 This is currently a work in progress and updated from the doc_updates
 branch of Rogue. New documentation is being added incrementally over time.
 
+Find other helpful links(slack channel, Jira, etc) `on confluence <https://confluence.slac.stanford.edu/spaces/ppareg/pages/610487593/Rogue+Documentation+Notification+Links>`_.
+
+
 .. toctree::
    :maxdepth: 3
    :caption: Contents:
 
+   introduction/index
+   tutorials/index
    installing/index
    pyrogue_tree/index
    interfaces/index

docs/src/installing/build.rst

@@ -22,7 +22,7 @@ Package Manager Install
 -----------------------
 
 Debian-based systems (Ubuntu 22.04 or later)
-########################
+############################################
 
 .. code::
 
@@ -37,7 +37,7 @@ Debian-based systems (Ubuntu 22.04 or later)
    $ sudo apt install python3-pyqt5.qtsvg
 
 RHEL-based systems (E.g. Rocky 9)
-########################
+#################################
 
 .. code::
 

docs/src/installing/docker.rst

@@ -70,7 +70,7 @@ GUI On A Linux OS
       -v <APP_DIR>:/python \
       ghcr.io/slaclab/rogue /python/<APP_NAME>
 
-GUI On A MAX OS
+GUI On A MAC OS
 ===============
 
 First install XQuartz. Then run it from the command line using `open -a XQuartz`. In the XQuartz preferences, go to the “Security” tab and make sure you’ve got “Allow connections from network clients” ticked.

docs/src/installing/firewall.rst

@@ -1,8 +1,8 @@
 .. _installing_firewall:
 
-####################################
+#####################################
 Rogue and Miniforge behind a firewall
-####################################
+#####################################
 
 To install rogue and miniforge behind a firewall you will need an ssl capable https proxy. I have used mitmproxy with success:
 

docs/src/installing/index.rst

@@ -4,9 +4,20 @@
 Installing & Compiling Rogue
 ============================
 
-The recommended method for installing rogue is :ref:`installing_miniforge`.
+This section describes how to obtain and install Rogue. 
+After installation is completed, consider following one of our :ref:`tutorials` to learn the basics. 
+
+The recommended method for installing rogue is on Linux systems through :ref:`installing_miniforge`. 
+If you chose to build rogue from source instead of using miniforge, the following list 
+is the recommendation for each operating system.
+
+**Note:** rogue installations are not currently supported on mac or windows hardware. 
+A Linux(Ubuntu) VM or docker image will be required to build rogue. 
+
+* Linux - :ref:`installing_full_build`
+* Windows - :ref:`installing_docker`
+* Mac - :ref:`installing_docker`
 
-This section describes how to obtain and install Rogue.
 
 .. toctree::
    :maxdepth: 1

docs/src/installing/miniforge.rst

@@ -6,12 +6,18 @@ Installing Rogue With Miniforge
 
 The following instructions describe how to install a pre-built Rogue package inside an miniforge environment. These instructions are relevant for Linux, Ubuntu on Windows and MacOS.
 
-See the section :ref:`installing_windows` for additional steps required for Windows.
+Windows installations will require you to install Ubuntu. Reference the section :ref:`installing_windows` for required steps. 
+Mac is not currently supported for rogue, and a VM or docker image is needed. Proceed to :ref:`installing_docker`. 
+
+Instructions for s3df setup are also available on `Confluence <https://confluence.slac.stanford.edu/spaces/ppareg/pages/591664140/Configure+miniforge+conda+and+Rogue+on+S3DF>`. 
 
 Getting Miniforge
-================
+=================
+
+Download and install miniforge if you don't already have it installed on your machine. Choose an install location with a lot of available diskspace (> 5GB). 
+Miniforge appears to only work reliably in the bash shell.
 
-Download and install miniforge if you don't already have it installed on your machine. Choose an install location with a lot of available diskspace (> 5GB). Miniforge appears to only work reliably in the bash shell.
+*Linux*
 
 .. code::
 
@@ -57,7 +63,7 @@ Alternatively you can install a specific released version of Rogue:
    $ conda create -n rogue_v6.5.0 -c conda-forge -c tidair-tag rogue=v6.5.0
 
 Using Rogue In Miniforge
-=======================
+========================
 
 No additional setup scripts need to be run Rogue in an miniforge environment. To activate and de-activate the Rogue environment you can use the following commands:
 
@@ -83,7 +89,7 @@ The following command is used to install Rogue inside and existing miniforge env
 
 
 Updating Rogue In Miniforge
-==========================
+===========================
 
 If you want to update Rogue, run the following command after activating the Rogue environment
 
@@ -92,7 +98,7 @@ If you want to update Rogue, run the following command after activating the Rogu
    $ conda update rogue -c tidair-tag
 
 Deleting Miniforge Environment
-=============================
+==============================
 
 Run the following commands to delete the miniforge environment.
 

docs/src/installing/miniforge_build.rst

@@ -1,14 +1,14 @@
 .. _installing_miniforge_build:
 
-==============================
+===============================
 Building Rogue Inside Miniforge
-==============================
+===============================
 
 This section provides instructions for downloading and building rogue inside an miniforge environment. These
 instructions are relevant for Linux
 
 Getting Miniforge
-================
+==================
 
 Download and install miniforge if you don't already have it installed on your machine. Choose an install location with a lot of available diskspace (> 5GB). Miniforge appears to only work reliably in the bash shell.
 
@@ -33,7 +33,7 @@ Set your local miniforge to use the update solver:
     $ conda config --set solver libmamba
 
 Downloading Rogue & Creating Miniforge Environment
-=================================================
+==================================================
 
 The next step is to download rogue and create a rogue compatible miniforge environment.
 
@@ -46,14 +46,15 @@ The next step is to download rogue and create a rogue compatible miniforge envir
 
 You now have an miniforge environment named rogue_build which contains all of the packages required to build and run rogue.
 
+You can alternatively clone the git repo with `git clone git@github.com:slaclab/rogue.git`.
 To activate this environment:
 
 .. code::
 
    $ conda activate rogue_build
 
 Building Rogue In Miniforge
-==========================
+============================
 
 Once the rogue environment is activated, you can build and install rogue
 
@@ -69,7 +70,7 @@ The Rogue build system will automatically detect that it is in a conda environme
 within the miniforge rogue environment.
 
 Using Rogue In Miniforge
-=======================
+=========================
 
 No additional setup scripts need to be run rogue in an miniforge environment. To activate and de-activate the rogue environment you can use the following commands:
 
@@ -86,7 +87,7 @@ To deactivate:
    $ conda deactivate
 
 Updating Rogue In Miniforge
-==========================
+===========================
 
 If you want to update and re-install rogue, run the following commands.
 
@@ -101,9 +102,22 @@ If you want to update and re-install rogue, run the following commands.
    $ make
    $ make install
 
-Deleting Miniforge Environment
+Building and Viewing the Docs
 =============================
 
+Note: if edits are made to the source files, the full build process needs to be run for changes to reflect in documentation.
+
+.. code::
+   # build the docs
+   $ cd ../docs/
+   $ make html
+
+   # view output on web browser
+   $ google-chrome build/html/index.html
+
+Deleting Miniforge Environment
+==============================
+
 Run the following commands to delete the miniforge environment.
 
 .. code::

docs/src/installing/yocto.rst

@@ -1,8 +1,8 @@
 .. _installing_yocto:
 
-=============================
+=========================
 Setting Up Rogue In Yocto
-=============================
+=========================
 
 Step 1 - Create a new application layer
 

docs/src/interfaces/index.rst

@@ -27,5 +27,7 @@ prototyped in Python and then re-implemented in C++ for performance.
    stream/index
    memory/index
    simulation/index
+   pyrogue/index
    sql.rst
+   cpp_api.rst