Merge pull request #949 from dapomeroy/update_documentation

Fix documentation issues

Author: dapomeroy

lib/ramble/docs/conf.py

@@ -196,13 +196,28 @@ def setup(sphinx):
     # Python classes that intersphinx is unable to resolve
     ("py:class", "argparse.HelpFormatter"),
     ("py:class", "contextlib.contextmanager"),
+    ("py:class", "func"),
     ("py:class", "module"),
     ("py:class", "_io.BufferedReader"),
+    ("py:class", "ramble.repository._PrependFileLoader"),
     ("py:class", "unittest.case.TestCase"),
     ("py:class", "_frozen_importlib_external.SourceFileLoader"),
     ("py:class", "clingo.Control"),
-    ("py:class", "six.moves.urllib.parse.ParseResult"),
     ("py:class", "TextIO"),
+    ("py:class", "llnl.util.argparsewriter.ArgparseCompletionWriter"),
+    ("py:class", "llnl.util.argparsewriter.ArgparseRstWriter"),
+    ("py:class", "llnl.util.argparsewriter.ArgparseWriter"),
+    ("py:class", "llnl.util.lock.Lock"),
+    ("py:class", "pandas.core.frame.DataFrame"),
+    ("py:class", "spack.environment.Environment"),
+    ("py:class", "spack.error.SpackError"),
+    ("py:class", "spack.error.SpecError"),
+    ("py:class", "spack.parse.Lexer"),
+    ("py:class", "spack.parse.Parser"),
+    ("py:class", "spack.package.Package"),
+    ("py:class", "spack.util.environment.EnvironmentModifications"),
+    ("py:class", "spack.util.executable.Executable"),
+    ("py:class", "spack.util.pattern.Composite"),
 ]
 
 # The reST default role (used for this markup: `text`) to use for all documents.

lib/ramble/docs/configuration_files.rst

@@ -213,7 +213,7 @@ Upload
 
 Ramble aims to support the upload of experiment outcomes (including FOMs), to
 SQL-like datastores. To do this we can specify an ``upload:type`` as defined by
-:mod:`ramble.experimental.uploader.Upload`, and a ``upload:uri`` to specify the
+:mod:`ramble.experimental.uploader.uploader_types`, and a ``upload:uri`` to specify the
 destination.
 
 As part of the upload it tries to attribute the data to a user. This can be
@@ -534,9 +534,9 @@ be searched for when looking for application definitions. Its format is as follo
 
 .. _software-config:
 
---------------
+-----------------
 Software Section:
---------------
+-----------------
 
 The software config section is used to define package definitions, and software
 environments created from those packages. Its format is as follows:

lib/ramble/docs/dev_guides/advanced_topics.rst

@@ -24,9 +24,9 @@ types supported in Ramble.
 
 .. _ramble-pipelines-and-phases:
 
-------------------------------
+-------------------------------
 Experiment Pipelines and Phases
-------------------------------
+-------------------------------
 
 Ramble has a concept of ``pipeline``, which represent full actions that can
 be taken on a workspace. Some of the common ``pipelines`` that are used are the

lib/ramble/docs/dev_guides/modifier_dev_guide.rst

@@ -23,7 +23,7 @@ This guide will provide general steps for creating a new modifier definition fil
 **NOTE:** Modifiers are considered a more advanced feature of Ramble. Writing a
 new modifier definition file in Ramble largely follows the same workflow as
 writing an application definition file, although the intent and behavior are
-different. It is recommended that you review :ref:`application-def-guide`
+different. It is recommended that you review :ref:`application-dev-guide`
 before writing a modifier.
 
 -----------

lib/ramble/docs/dev_guides/package_manager_dev_guide.rst

@@ -27,7 +27,7 @@ definition file.
 Writing a new pcakage manager definition file in Ramble largely follows the
 same workflow as writing an application definition file, although the intent
 and behavior are different. It is recommended that you review
-:ref:`application-def-guide` before writing a modifier.
+:ref:`application-dev-guide` before writing a modifier.
 
 -----------
 Preparation

lib/ramble/docs/index.rst

@@ -22,18 +22,20 @@ If you're new to Ramble and want to start using it, see :doc:`getting_started`.
    :maxdepth: 2
    :caption: Basics
 
-   ramble
    getting_started
    configuration_files
    workspace
    workspace_config
    package_managers
    success_criteria
+   results
+   mirror_config
 
 .. toctree::
    :maxdepth: 2
    :caption: Reference
 
+   ramble
    command_index
 
 .. toctree::

lib/ramble/docs/mirror-config.rst renamed to lib/ramble/docs/mirror_config.rst

@@ -7,7 +7,7 @@
    except according to those terms.
 
 
-.. _package_manager_control:
+.. _package-manager-control:
 
 ================
 Package Managers
@@ -113,7 +113,7 @@ determine what packages to install within the resulting virtual environment.
 The use of this package manager requires ``pip`` to be installed outside of
 Ramble. This happens automatically in several Python installations. For more
 information see
-`pip's documentation<https://pip.pypa.io/en/stable/installation/>`_.
+`pip's documentation <https://pip.pypa.io/en/stable/installation/>`_.
 
 ^^^^^^^^^^^^^^^^^^^^^
 Spack Package Manager

lib/ramble/docs/package_managers.rst

@@ -4,5 +4,8 @@ sphinx_rtd_theme
 sphinxcontrib-programoutput
 sphinxcontrib-jquery
 sphinx-copybutton
-tdqm
+tqdm
 deprecation
+pytest
+pandas
+matplotlib

lib/ramble/docs/requirements.txt

@@ -6,11 +6,11 @@
    option. This file may not be copied, modified, or distributed
    except according to those terms.
 
-.. _workspace:
+.. _results:
 
-================
+==============
 Ramble Results
-================
+==============
 
 Ramble provides support and tooling around processing results data.
 
@@ -20,9 +20,9 @@ Most notably, the two supported functionalities are:
   * Uploading of stand alone JSON in ramble-output format
   * Generation of plots and analysis as part of a report
 
--------------------
+------
 Upload
--------------------
+------
 
 The ``ramble results upload`` command is used to import experiment results from
 a JSON file, and upload them as specified in the upload block of Ramble's
@@ -31,9 +31,9 @@ config file (see :ref:`config documentation<upload-config-option>`).
 This can be used for both results from an arbitrary ramble workspace, or for
 data that is generated by tools which conform to rambles data schema.
 
--------------------
+------
 Report
--------------------
+------
 The ``ramble results report`` command is experimental functionality that provides
 the user a way to generate plots and reports from the output of a workspace.
 This output is in the form of individual `png` plots, and a combined `pdf`
@@ -47,9 +47,9 @@ Multiple plot types are supported, to aid in comparison of runs and common tasks
 For these plots, common operations are supported such as log axis, data
 grouping, and idealized line plotting.
 
-^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Strong and Weak Scaling Plots
-^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Activated by either the ``strong-scaling`` or ``weak-scaling`` subcommand, these plots generate a line plot and attempt to annotate idealized scaling based on the data input.
 
@@ -73,9 +73,9 @@ Another common use case might be to plot data by context (such as in OMB), which
 
 Other compelling options include ``-n`` to normalize the plot y values, or ``--logx``/``--logy`` for log axes.
 
-^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^
 Comparison and FOM plots
-^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 A comparison plot compares a specific FOM across all valid experiments, and generates a bar plot with one bar per experiment. It can be invoked by:
 

lib/ramble/docs/results.rst

@@ -116,7 +116,7 @@ The above example shows the full interface for defining success criteria with
 * ``fom_context``: (Optional) The context ``fom_name`` should exist in. Defaults to ``null``.
 
 Both ``fom_name`` and ``fom_context`` support
-`python style globbing<https://docs.python.org/3/library/fnmatch.html>`_.
+`python style globbing <https://docs.python.org/3/library/fnmatch.html>`_.
 
 When using the globbing functionality, all contexts that match the
 ``fom_context`` argument are searched. Within each context, all FOMs that match

lib/ramble/docs/success_criteria.rst

@@ -145,7 +145,7 @@ experiment run directories to see what changed after applying the ``lscpu``
 modifier.
 
 Advanced Modifiers
------------------
+------------------
 
 Some modifiers have additional functionality, which can include requiring
 specific software packages to be present. An example of this is the

lib/ramble/docs/tutorials/10_using_modifiers.rst

@@ -6,7 +6,7 @@
    option. This file may not be copied, modified, or distributed
    except according to those terms.
 
-.. _modifying_an_experiment_tutorial:
+.. _modifying_a_gromacs_experiment_tutorial:
 
 =======================================
 3) Modifying A GROMACS Experiment
@@ -203,7 +203,7 @@ This command opens the ``ramble.yaml`` file, along with any ``*.tpl`` files in
 the workspace's ``configs`` directory. The root directory of the workspace can
 be seen in the ``Location`` attribute output from:
 
-.. code-blocks:: console
+.. code-block:: console
 
     $ ramble workspace info
 

lib/ramble/docs/tutorials/3_modifying_a_gromacs_experiment.rst

@@ -6,7 +6,7 @@
    option. This file may not be copied, modified, or distributed
    except according to those terms.
 
-.. _modifying_an_experiment_tutorial:
+.. _changing_a_software_stack_tutorial:
 
 ============================
 5) Changing A Software Stack

lib/ramble/docs/tutorials/5_changing_your_software_stack.rst

@@ -165,7 +165,7 @@ Your final configuration file should look something like:
 .. include:: shared/wrf_execute.rst
 
 **NOTE** Some of these experiments can take a while to execute. Experiments can
-be filtered using the :ref:`--where<filter-experiments>`` option to execute the
+be filtered using the :ref:`--where <filter-experiments>` option to execute the
 higher scale experiments if desired. To do this, try:
 
 .. code-block:: console

lib/ramble/docs/tutorials/7_using_zips_and_matrices.rst

@@ -65,7 +65,7 @@ contents of ``$RAMBLE_ROOT/examples/vector_matrix_gromacs_config.yaml``:
 requires ``spack`` is installed and available in your path. Modifications to
 the ``package_manager`` variant will change this behavior.
 
-.. literalinclude:: ../../../../examples/vector_matrix_gromacs_config.yaml
+.. literalinclude:: /../../../examples/vector_matrix_gromacs_config.yaml
    :language: YAML
 
 Note that specifying compilers that Spack doesn't have installed may take a while.

lib/ramble/docs/tutorials/shared/gromacs_vector_workspace.rst

@@ -75,7 +75,7 @@ contents of ``$RAMBLE_ROOT/examples/basic_gromacs_config.yaml``:
 requires ``spack`` is installed and available in your path. Modifications to
 the ``package_manager`` variant will change this behavior.
 
-.. literalinclude:: ../../../../examples/basic_gromacs_config.yaml
+.. literalinclude:: /../../../examples/basic_gromacs_config.yaml
    :language: YAML
 
 Note that specifying compilers that Spack doesn't have installed may take a while.

lib/ramble/docs/tutorials/shared/gromacs_workspace.rst

@@ -30,7 +30,7 @@ final configuration from a previous tutorial.
 requires ``spack`` is installed and available in your path. Modifications to
 the ``package_manager`` variant will change this behavior.
 
-.. literalinclude:: ../../../../examples/wrf_scaling_config.yaml
+.. literalinclude:: /../../../examples/wrf_scaling_config.yaml
    :language: YAML
 
 The above configuration will execute 2 experiments, comprising a basic scaling

lib/ramble/docs/tutorials/shared/wrf_scaling_workspace.rst

@@ -421,7 +421,7 @@ the installation and generate software environments for each experiment.
 
 As an example, if the applications and workspace configuration file provide a
 configuration for Spack, Ramble will generate
-`Spack environments<https://spack.readthedocs.io/en/latest/environments.html>`_.
+`Spack environments <https://spack.readthedocs.io/en/latest/environments.html>`_.
 
 By default, Ramble uses the following format for creating a spack environment file: