Merge pull request #154 from cgay/dev

Testworks docs

.gitmodules

@@ -10,3 +10,6 @@
 [submodule "ext/strings"]
 	path = ext/strings
 	url = https://github.com/dylan-lang/strings
+[submodule "ext/sphinx-extensions"]
+	path = ext/sphinx-extensions
+	url = https://github.com/dylan-lang/sphinx-extensions

documentation/.gitignore

@@ -0,0 +1,2 @@
+_build
+build

documentation/source/conf.py

@@ -0,0 +1,111 @@
+# -*- coding: utf-8 -*-
+#
+# Testworks documentation build configuration file, created by
+# sphinx-quickstart on Fri Oct 26 11:31:31 2012.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../../ext/sphinx-extensions/sphinxcontrib'))
+import dylan.themes as dylan_themes
+
+# -- Project information -----------------------------------------------------
+
+project = 'dylan-libraries'
+copyright = '2022, Dylan Hackers'
+author = 'Dylan Hackers'
+
+
+# -- General configuration -----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'dylan.domain',
+    'sphinx.ext.intersphinx'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The primary domain.
+primary_domain = 'dylan'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = dylan_themes.get_html_theme_default()
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+html_theme_options = dylan_themes.get_html_theme_options_default()
+
+# Add any paths that contain custom themes here, relative to this directory.
+html_theme_path = [dylan_themes.get_html_theme_path()]
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+html_title = "Testworks"
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Testworks'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'Testworks.tex', u'Testworks', u'Dylan Hackers', 'manual'),
+]
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'testworks', u'Testworks', [u'Dylan Hackers'], 1)
+]
+
+
+# -- Options for Texinfo output ------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('index', 'Testworks', u'Testworks',
+   u'Dylan Hackers', 'Testworks', 'One line description of project.',
+   'Miscellaneous'),
+]
+
+
+# -- Options for Epub output ---------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = u'Testworks'
+epub_author = u'Dylan Hackers'
+epub_publisher = u'Dylan Hackers'
+epub_copyright = u'2022, Dylan Hackers'

documentation/users-guide/source/copyright.rst → documentation/source/copyright.rst

@@ -2,7 +2,7 @@ Copyright
 *********
 
 
-Copyright © 2011-2012 Dylan Hackers.
+Copyright © 2011-2022 Dylan Hackers.
 
 Portions copyright © 1995-2000 Functional Objects, Inc.
 
@@ -35,4 +35,4 @@ of their respective holders.
 ------
 
 In particular, large parts of this documentation resulted from the
-work of Judy Anderson, Shri Amit and Andy Armstrong at Harlequin.
+work of Judy Anderson, Shri Amit and Andy Armstrong at Harlequin.

documentation/users-guide/source/index.rst → documentation/source/index.rst

@@ -1,5 +1,6 @@
-Testworks User Guide
-====================
+*********
+Testworks
+*********
 
 .. toctree::
    :maxdepth: 3

documentation/users-guide/source/reference.rst → documentation/source/reference.rst

@@ -1,3 +1,4 @@
+*******************
 Testworks Reference
 *******************
 
@@ -9,21 +10,17 @@ Testworks Reference
 
 See also: :doc:`usage`
 
-
-The Testworks Module
-====================
+The *testworks* library exports a single module named *testworks*.
 
 Suites, Tests, and Benchmarks
------------------------------
+=============================
 
 .. macro:: test-definer
 
    Define a new test.
 
-   :signature: define test *test-name*
-                   (#key *expected-to-fail-reason, expected-to-fail-test, tags*)
-                 *body*
-               end
+   :signature:
+      define test *test-name* (#key *expected-to-fail-reason, expected-to-fail-test, tags*) *body* end
    :parameter test-name: Name of the test; a Dylan variable name.
    :parameter #key expected-to-fail-reason: A :drm:`<string>` or ``#f``.
       The reason this test is expected to fail.
@@ -63,10 +60,8 @@ Suites, Tests, and Benchmarks
 
    Define a new benchmark.
 
-   :signature: define benchmark *benchmark-name*
-                   (#key *expected-to-fail-reason, expected-to-fail-test, tags*)
-                 *body*
-               end
+   :signature:
+      define benchmark *benchmark-name* (#key *expected-to-fail-reason, expected-to-fail-test, tags*) *body* end
    :parameter benchmark-name: Name of the benchmark; a Dylan variable name.
    :parameter #key expected-to-fail-reason: A :drm:`<string>` or ``#f``.
       The reason this benchmark is expected to fail.
@@ -252,7 +247,7 @@ Suites, Tests, and Benchmarks
        ``expected-to-fail-reason: "foo"``.
 
 Assertions
-----------
+==========
 
 Assertions are the smallest unit of verification in Testworks.  They
 must appear within the body of a test.
@@ -500,7 +495,7 @@ These are the available assertion macros:
 
 
 Checks
-------
+======
 
 Checks are deprecated; use `Assertions`_ instead.  The main difference between
 checks and assertions is that the check macros do not cause termination of the
@@ -630,7 +625,7 @@ These are the available checks:
 
 
 Test Execution
---------------
+==============
 
 .. function:: run-test-application