dylan-lang/sphinx-extensions

Extensions to Sphinx for the Open Dylan website and documentation

These are extensions for Sphinx that we use in the construction of our website and documentation.

This repository is usually pulled into the appropriate places as a git submodule.

See https://github.com/dylan-lang/sphinx-extensions/blob/master/documentation/source/index.rst for documentation on the "dylan" Sphinx domain.

sphinx-extensions's Issues

Python 3 changes needed

• urlparse is renamed to urllib.parse
• Can't import drmindex (but can from dylandomain import drmindex or from . import drmindex)
• dict merges for option_spec values doesn't work as is.

dylandomain: can't linewrap in middle of ref

If you try to wrap text in the middle of an xref like this:

     The ``<semaphore>`` class is a class representing a traditional
     counting semaphore. An instance of ``<semaphore>`` contains a
     counter in its internal state. Calling :meth:`release
     <release(<semaphore>)>` on a semaphore increments the internal

you get an error like this:

/.../core-reference/source/threads.rst:776: ERROR: Invalid syntax for :dylan:meth: role; `release
<release(<semaphore>)>` should be like `ref` or `text <ref>`.
/.../core-reference/source/threads.rst:984: ERROR: Invalid syntax for :dylan:meth: role; `wait-for
<wait-for(<recursive-lock>)>` should be like `ref` or `text <ref>`.

variable definition adjective macro

We have things that are currently flagged as Variable definition adjective ... these are used for (at least) thread and locked macros.

dylandomain: missing specializer -> bad error

When missing a specializer on a method, you get an error like this instead of something nice:

Exception occurred:
  File ".../documentation/sphinx-extensions/dylandomain/dylandomain.py", line 401, in fullname
    specializer = self.options['specializer']
KeyError: 'specializer'

Improve generated HTML for `module` directive

The HTML generated for the module directive (:mod:`foo`) looks exactly like the HTML for other Dylan language entities. Given that we will normally use .. module:: foo to start a module reference section I think we have two choices:

1. Generate a section header for the module:

   The Foo Module

2. Just create an anchor to reference but leave the section header to be created manually. I'm thinking this might be necessary because we don't know what section level to use. (i.e., what character to use for underlining)

dylandomain: documenting constants

We need a new object type for constant.

An example of this can be found in the transcendentals documentation:

$single-pi
----------

Constant
--------

Summary

The value of π as a single precision floating point number.

Type

<single-float>

Superclass

<float>

Description

The value of π as a single precision floating point number.

See also

See the constant `$double-pi`_.

Links to methods on the same GF are indistinguishable.

Look at the documentation for the decode-duration generic function There are two method links in the "See also" section that look exactly the same despite being defined in the RST document as

   See also

   - :meth:`decode-duration <decode-duration(<day/time-duration>)>`
   - :meth:`decode-duration <decode-duration(<year/month-duration>)>`

Note that the link targets are correct.

Improve `.. constant::` directive

We should be able to specify a constant's type as in .. constant:: $foo :: <type>.

index.rst:43: WARNING: Error in "constant" directive:
maximum 1 argument(s) allowed, 3 supplied.

.. constant:: $day :: <duration>

I assume it's the same for the .. variable:: directive.

In the generated output it should look something like $foo :: <type> Constant

dylandomain: make latexpdf fails

When I try to make latexpdf, I get this error:

processing CoreReference.tex... index copyright language extensions table-extensions
  threads numbers mwords transcend lid 
resolving references...

Exception occurred:
  File ".../documentation/sphinx-extensions/dylandomain/dylandomain.py", line 694, in resolve_xref
    library = node.dylan_curlibrary
AttributeError: 'pending_xref' object has no attribute 'dylan_curlibrary'

drm: Can't line wrap in middle of :drm: role.

This is the same thing as issue #3.

Module and function directives conflict

If you have a function named print and a module named print, it's a crap shoot whether :mod:`print` will take you to the module or the function. I assume we can fix this by automatically appending -module to the Sphinx object id.

Need better support for multi-methods

A current example that is a bit of a conundrum for me....

The transcendentals module has a lot of functions that have 4 methods. For example, take atan2:

atan2(<single-float>, <single-float>)
atan2(<double-float>, <single-float>)
atan2(<single-float>, <double-float>)
atan2(<double-float>, <double-float>)

How to document these?

Problem 1: Obviously we don't want to duplicate the entire section of documentation for all four methods, but there doesn't seem to be any way to reference a particular method specialization's documentation. It's common to do a minor conversion and then call the "primary" method.

Problem 2: Even if we could reference a particular method specialization, I suspect there would be many cases (and atan2 is an example) where it would be easier to read the documentation if it were all in a single section listing all method specializations. A natural way to do this would be to allow multiple :specializer: annotations under one .. method:: atan2. I'm also thinking perhaps we should allow :specializer: to be used (multiple times) under .. generic-function:: for cases like this where everything is sealed and all methods are known.

(If we do allow multiple :specializer: annotations, it will have an effect on how we solve the "reference a particular method" problem.)

I don't have it all figured out, obviously. Anyone have thoughts on this?

dylandomain: 'make json' fails when no dylan domain usage

Reproduce:

cd documentation/system-io-reference
make json

Get failure:

  File "/Users/bruce/Development/dylan/opendylan/documentation/sphinx-extensions/dylandomain/dylandomain.py", line 610, in clear_doc
    for fullid, (objects_docname, _, _, _, _) in self.data['objects'].items():
KeyError: 'objects'

It is important to note that system-io-reference doesn't yet use dylandomain.

dylandomain: uses wrong URL for DRM

The dylandomain should be using the same URL as the DRM does now (without the www.) ... this avoids issues with redirects and anchors.