Merge branch 'master' into 355-allow-all-api-scripts-to-take-dictionary

README.rst

@@ -41,7 +41,7 @@ Rater Scoring Modeling Tool (RSMTool) is a python package which automates and co
 
 We expect the primary users of RSMTool to be researchers working on developing new automated scoring engines or on improving existing ones. Note that RSMTool is not a scoring engine by itself but rather a tool for building and evaluating machine learning models that may be used in such engines. 
 
-For installation and usage, please see the `official documentation <http://rsmtool.readthedocs.io>`_. 
+For installation and usage, please see the `official documentation <https://rsmtool.readthedocs.io>`_.  If you use the `Dash <https://kapeli.com/dash>`_ app on macOS, you can also download the complete RSMTool documentation for offline use. Go to the Dash preferences, click on "Downloads", then "User Contributed", and search for "RSMTool".
 
 Requirements
 ------------

doc/Makefile

@@ -17,4 +17,10 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+dash: export DASH=True
+dash: clean
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	python "$(SOURCEDIR)/add_dash_anchors.py" "$(BUILDDIR)/html"
+	doc2dash -n RSMTool -d "$(BUILDDIR)" -I index.html "$(BUILDDIR)/html"
+	cp assets/dash_icon.png "$(BUILDDIR)/RSMTool.DocSet/icon.png"

doc/add_dash_anchors.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Add Dash-style anchors to already-generated HTML documentation.
+
+This script iterates over pre-specified HTML files generated via
+sphinx-build, finds all of the sections, and adds Dash-style anchors
+so that when those HTML files are displayed in the Dash macOS app,
+the sections are displayed in a Dash TOC on the right.
+
+:author: Nitin Madnani (nmadnani@ets.org)
+:organization: ETS
+"""
+
+import argparse
+import logging
+import re
+import pathlib
+import unicodedata
+from urllib.parse import quote
+
+from bs4 import BeautifulSoup
+
+# pre-define the list of HTML files we want to miodify
+FILES_TO_MODIFY = ["advanced_usage.html", "api.html", "contributing.html",
+                   "custom_notebooks.html", "evaluation.html",
+                   "getting_started.html", "pipeline.html",
+                   "internal.html", "tutorial.html",
+                   "usage_rsmtool.html", "utilities.html", "who.html"]
+PILCROW = unicodedata.lookup('PILCROW SIGN')
+
+
+def main():  # noqa: D103
+
+    # set up an argument parser
+    parser = argparse.ArgumentParser(prog='add_dash_anchors.py')
+    parser.add_argument("htmldir",
+                        type=pathlib.Path,
+                        help="path to the already-built HTML documentation")
+
+    # parse given command line arguments
+    args = parser.parse_args()
+
+    # set up the logging
+    logging.basicConfig(format='%(levelname)s:%(message)s', level=logging.INFO)
+
+    # iterate over all the built HTML files
+    for htmlfile in args.htmldir.glob("**/*.html"):
+
+        # we only care about the pre-specified html files
+        if htmlfile.name in FILES_TO_MODIFY:
+
+            logging.info(f'Processing {htmlfile.name} ...')
+
+            # parse the file
+            with open(htmlfile, 'r') as htmlfh:
+                soup = BeautifulSoup(htmlfh, features='html.parser')
+
+            # each HTML file has a main section which we do not need
+            # but we need _all_ of the other sections
+            sections = soup.body.div.find_all("div", class_="section")[1:]
+            for section in sections:
+                section_title = section.find(re.compile(r'^h[0-9]')).text
+                section_title = section_title.rstrip(PILCROW)
+
+                # convert this title to percent-encoded format which will be
+                # the name of our entry
+                entry_name = quote(section_title)
+                entry_type = 'Section'
+                anchor_name = f"//apple_ref/cpp/{entry_type}/{entry_name}"
+
+                # create a new anchor tag for this subsection
+                anchor_tag = soup.new_tag('a',
+                                          attrs={'name': anchor_name,
+                                                 'class': "dashAnchor"})
+
+                # insert this new tag right before the section
+                section.insert_before(anchor_tag)
+
+            # overwrite the original HTML file
+            with open(htmlfile, 'w') as outfh:
+                outfh.write(str(soup))
+
+
+if __name__ == '__main__':
+    main()

doc/api.rst

@@ -61,6 +61,7 @@ From :py:mod:`~rsmtool.configuration_parser` Module
     :members:
     :undoc-members:
     :show-inheritance:
+    :exclude-members: deprecated_positional_argument
 
 From :py:mod:`~rsmtool.container` Module
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~