Merge pull request #38 from dylan-lang/toc-entries-for-definitions

Toc entries for definitions

Author: cgay

documentation/source/conf.py

@@ -4,15 +4,10 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+# Use the local repo to build the docs, as a very minimal test.
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../../sphinxcontrib'))
 
 
 # -- Project information -----------------------------------------------------
@@ -22,7 +17,7 @@
 author = 'Dylan Hackers'
 
 # The full version, including alpha/beta/rc tags
-release = 'v0.2.0'
+release = 'v1.1.0'
 
 
 # -- General configuration ---------------------------------------------------
@@ -31,7 +26,9 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'dylan.domain',
 ]
+primary_domain = 'dylan'
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -52,4 +49,4 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []

documentation/source/index.rst

@@ -36,6 +36,14 @@ Roles
    configured by `dylan_drm_index`_. The partial URL is appended to the base URL
    configured by the `dylan_drm_url`_.
 
+   For example, this link to :drm:`<object>` was produced with the markup
+   ``:drm:`<object>```, which assumes the above configuration setting of ``primary_domain
+   = 'dylan'``.
+
+.. The above usage of the :drm: role is explicitly included as a very minimal test to
+   make sure that when this documentation is built it at least uses some of the code in
+   dylandomain.py; please don't remove it.
+
 
 Configurables
 -------------
@@ -53,7 +61,7 @@ Configurables
    partial URLs. Each line is a correspondence. The first word is the Dylan
    name, followed by whitespace, then the remainder is the partial URL. Defaults
    to partial URLs corresponding to the copy of the `Dylan Reference Manual`:t:
-   at `<http://opendylan.org>`_.
+   at `opendylan.org <https://opendylan.org>`_.
 
 
 Library, module, and binding documentation
@@ -443,6 +451,17 @@ Directive options
 Directive options appear immediately after the directive with no intervening
 blank lines.
 
+``:no-contents-entry:``
+^^^^^^^^^^^^^^^^^^^^^^^
+
+   Tells Sphinx not to add a Table of Contents (ToC) entry for this Dylan object.  This
+   may be especially useful for `dylan:method::`_ directives because sometimes they can
+   unnecessarily clutter the ToC. If the `dylan:method::`_ directives are all colocated
+   with the `dylan:generic-function::`_ directive then it may be sufficient to only
+   include the latter in the ToC. (This option is provided by Sphinx itself.)
+
+   :Syntax: ``:no-contents-entry:``
+
 ``:library:``
 ^^^^^^^^^^^^^
 

sphinxcontrib/dylan/domain/__init__.py

@@ -11,5 +11,7 @@
 from .dylandomain import DylanDomain
 
 def setup (app):
+    # https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_config_value
     app.add_config_value('dylan_drm_url', 'https://opendylan.org/books/drm/', 'html')
+    # https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_domain
     app.add_domain(DylanDomain)