Fix documentation issues

Fix various documentation issues like broken formatting and links.

Author: dapomeroy

lib/ramble/docs/conf.py

@@ -201,8 +201,8 @@ def setup(sphinx):
     ("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", "func"),
 ]
 
 # 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

@@ -29,6 +29,8 @@ If you're new to Ramble and want to start using it, see :doc:`getting_started`.
    workspace_config
    package_managers
    success_criteria
+   results
+   mirror_config
 
 .. toctree::
    :maxdepth: 2

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

@@ -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

@@ -8,9 +8,9 @@
 
 .. _workspace:
 
-================
+==============
 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

@@ -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

@@ -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:: $RAMBLE_ROOT/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

@@ -403,7 +403,7 @@ Variant Control
 Within a workspace configuration file, experiments are able to define variants.
 Variants are able to manipulate specific aspects of experiments and
 applications. More information on these configuration options can be seen in
-the :ref:`Variants Configuration Section<variants-config>` documentation. To
+the :ref:`Variants Configuration Section <variants-config>` documentation. To
 begin with, the only variant that can be specific is the ``package_manager``.
 
 The ``package_manager`` variant is used to define which package manager is used
@@ -806,7 +806,7 @@ This config section is defined in the
 
 Below are examples of using this within a workspace config file.
 
-""""""""""""""""""
+
 Custom Executables
 """"""""""""""""""
 
@@ -831,7 +831,7 @@ The above example creates a custom executable, named ``lscpu`` that will inject
 the command ``lscpu`` into the command for an experiment when it is used. It is
 important to note that this only creates the executable, and does not use it.
 
-""""""""""""""""""""""""""""
+
 Controlling Executable Order
 """"""""""""""""""""""""""""
 

lib/ramble/docs/workspace_config.rst

@@ -507,7 +507,7 @@ def build_used_variables(self, workspace):
         variables referenced by any of them are tracked properly.
 
         Args:
-            workspace (Workspace): Workspace to extract templates from
+            workspace (ramble.workspace.Workspace): Workspace to extract templates from
 
         Returns:
             (set): All variable names used by this experiment.

lib/ramble/ramble/application.py

@@ -298,7 +298,7 @@ def find_workspace_path(args):
         args (argparse.Namespace): argparse namespace with command arguments
 
     Returns:
-        (string): Path to workspace root, or None
+        (str): Path to workspace root, or None
     """
 
     # treat workspace as a name

lib/ramble/ramble/cmd/__init__.py

@@ -120,7 +120,7 @@ def all_object_attributes(obj):
     definitions in) and return a list of such attributes.
 
     Returns:
-        (list) all_attrs: List of all attributes the object contains
+        (list): List of all attributes the object contains
     """
     all_attrs = []
     for name in obj_attribute_map:

lib/ramble/ramble/cmd/common/info.py

@@ -111,12 +111,13 @@ def create_context_from_dict(context_name, in_dict):
         'exclude': {},
         'zips': {},
         'matrices': {} or [],
-        'tags': []
-        'n_repeats': '',
+        'tags': [],
+        'n_repeats': ''
+        }
 
     Args:
-        context_name: The name of the context (e.g., application name)
-        in_dict: A dictionary representing the variable definitions
+        context_name (str): The name of the context (e.g., application name)
+        in_dict (dict): A dictionary representing the variable definitions
 
     Returns:
         Context(object)

lib/ramble/ramble/context.py

@@ -135,7 +135,8 @@ def relative_indices(self, relative_to):
         """Compute node indices relative to another node
 
         Args:
-            relative_to (node): node to shift current node's indices relative to
+            relative_to (ExpansionNode): node to shift current node's indices
+                relative to
 
         Returns:
             (tuple) indices of shifted match set
@@ -146,7 +147,8 @@ def add_children(self, children):
         """Add children to this node
 
         Args:
-            children (node, or list): nodes to adds as children of self
+            children (ExpansionNode, or list): nodes to adds as children of
+                self
         """
         if isinstance(children, list):
             self.children.extend(children)
@@ -173,13 +175,15 @@ def define_value(
 
         Args:
             expansion_dict (dict): variable definitions to use for expanding
-            detected matches
+                detected matches
             allow_passthrough (bool): if true, expansion is allowed to fail. if
-            false, failed expansion raises an error.
+                false, failed expansion raises an error.
             expansion_func (func): function to use for expansion of nested
-            variable definitions
-            evaluation_func (func): function to use for evaluating math of strings
-            no_expand_vars (set): set of variable names that should never be expanded
+                variable definitions
+            evaluation_func (func): function to use for evaluating math of
+                strings
+            no_expand_vars (set): set of variable names that should never be
+                expanded
         """
         if no_expand_vars is None:
             no_expand_vars = set()
@@ -626,7 +630,7 @@ def evaluate_predicate(self, in_str, extra_vars=None, merge_used_stage: bool = T
             extra_vars: Variable definitions to use with highest precedence
 
         Returns:
-            boolean: True or False, based on the evaluation of in_str
+            bool: True or False, based on the evaluation of in_str
         """
 
         evaluated = self.expand_var(