SphinxRefmate

“A referencing toolkit to assist with the creation of Sphinx Documentation projects in restructured text.”

About

SphinxRefmate is a Sublime Text plugin designed as a minimal hassle reference manager for use in the development of Sphinx Documentation projects in restructured Text. The plugin can gather a variety of reference types from Sphinx projects, on demand, and present these to the user in the form of a Sublime Text quick-panel. This menu can be fuzzy-searched so that a reference can be easily located, and clicked. This will then insert the correct piece of restructured text into the current document, at the current cursor position, in the correct format e.g. a citation reference pointing to the desired citation.

Reference Types Supported

The following reference types can be gathered from within the currently active Sphinx Doc project:

• Bibliography citations (reST [author_1966]_)
• Substitutions (reST |subst|)

The following reference types can be gathered from the local Sphinx Doc project, and additionally any associated Sphinx Doc projects identifiable through the active intersphinx_mapping variable:

• Section labels/references (reST :ref:)
• Page references (reST :doc:)
• Glossary terms (reST :term:)

Save Time and Head Scratching

If, for example, you are editing a restructured text page of a Sphinx Docs web project, and you want to insert a hyperlink to a page you created about 'London Buses' a few weeks ago - but you can't remember its reference name - with Sphinx Refmate you can simply click the Insert Links To Current Project entry under the Tools -> Sphinx Refmate menu (or access this command via another method e.g. a user defined key binding) and a quick-panel list will be brought up which includes all the doc (page) links in the current Sphinx project. You can then begin typing 'London Bu..' in the selection header of the quick-panel, and in doing so the precise 'doc' style link you require will become visible through the filtering, and you can click on it to insert a nicely formatted reST link. (N.B. Regular Sublime Text menus, as well as configurable key bindings, are available for all the Sphinx Refmate commands.)

Installation

Installation should be carried out using the Sublime Package Manager.

• Ctrl+Shift+P or Cmd+Shift+P in Linux/Windows/OS X
• type install, select Package Control: Install Package
• type sphinx, select SphinxRefmate

It is also possible to clone from the SphinxRefmate github repository directly into your Sublime Text Packages directory.

Usage

Pull up the command palette via key binding or menu: Tools -> Command Palette and type Sphinx Refmate to bring up all the commands.

– or –

Use the right-click context menu (by default, only available when you're in a text.restructuredtext scope). Right clicking brings up various choices through Sphinx Refmate -> various submenus.

Note: The context menu can be completely disabled, or made context independent, via the plugin settings (see below) if required.

– or –

Use the main topbar menu in Sublime Text: Tools -> Sphinx Refmate -> various submenus

Settings

Plugin settings can be edited via Preferences -> Package Settings -> Sphinx Refmate -> Settings. Below is a list of all the available SphinxRefmate settings, and their impact on plugin functionality.

“sphinx_check”: true

This setting determines whether Sphinx Refmate will check if it's running in a Sphinx Doc project before running plugin features (checks for top folder conf.py). Set to false to run in any environment.

“enable_context_menu”: true

When this is set to true the 'right-click' context menu will show Sphinx Refmate menus in a restructuredText scope (or all scopes if rst_check is set to false). Set enable_context_menu to false to disable Sphinx Refmate context menus completely.

“rst_check”: true

This setting determines whether Sphinx Refmate will check if the edit cursor is in a restructured text context (scope) before running plugin features. Set to false to run in any scope.

“priv_project_prefix”: “priv”

Sphinx Refmate utilises an 'intersphinxmapping' variable (see below) within which Sphinx Doc projects are defined by a short name key. If this name key begins with the _priv_project_prefix (default 'priv'), then Sphinx Refmate will consider this project private rather than public e.g. a local lan based html site rather than internet based. It is important for Sphinx Refmate to differentiate between private and public projects as unreachable links to private sites should not be offered up for insertion when editing public sites.

“intersphinx_map_source_list”: [“filename1.py”, “filename2.py”]

SphinxRefmate locates reST :ref:, :doc: and :term: style references by parsing a Sphinx Doc database file called objects.inv. This file usually resides at the root of the Sphinx Doc build tree and is an integral feature of the Sphinx project build process. The way Sphinx Refmate understands where to look for this or that project's objects.inv file is via the intersphinx_mapping dictionary, which is usually defined in a Sphinx Doc project's conf.py. The intersphinx_map_source_list is used to provide a list of file locations in which the necessary intersphinx_mapping variable is likely to be found. Sphinx Refmate parses these files in turn and uses the first intersphinx_mapping variable found in order to locate objects.inv files for some or all of the projects therein defined. When an objects.inv file is located, Sphinx Refmate parses it to build a reference list. This is a reference list for one Sphinx Doc project, and Sphinx Refmate can use this, on its own or along with other such lists, to populate the quick-panel.

Note: The intersphinx_mapping variable is normally associated with the Sphinx Doc Intersphinx extension, and its main function is to associate/map a number of Sphinx Doc project names (actually short aliases) to the filepath location of their objects.inv file, in order that Intersphinx can manage multiple project cross referencing at build time. The Sphinx Refmate Sublime Text plugin uses this same intersphinx_mapping variable to make manageing multiple project cross referencing at design time significantly easier. To use Sphinx Refmate successfully across multiple projects you need to have a modicum of understanding concerning the design of an intersphinx_mapping variable. See the section on intersphinx_mapping variables below, if required.

“bib_ref_file_list”: [“filename1.rst”, “filename2.rst”]

When called upon to do so, SphinxRefmate scans, in turn, all of the files in the bib_ref_file_list in order to compile a list of restructured text citations. The citations sought are those of a standard restructured text variety, see docutils reST/citations for more details. Note that this feature is designed to function solely within one project, which is in line with the intra-project manner in which sphinx treats reST citations, see: Sphinx Doc citations.

“rst_epilog_source_list”: [“filename1.py”, “filename2.py”]

When called upon to do so, SphinxRefmate scans, in turn, all of the files in the rst_epilog_source_list in order to compile a list of restructured text substitutions from those defined in all rst_epilog = or rst_epilog += assignment statements. These files should be python source code files, and it is likely that you may need only one defined - the standard Sphinx Docs configuration file: conf.py. The substitutions sought within any discovered rst_epilog variable are those defined according to restructured text standards, see docutils reST/substitutions for more details. Note that this feature is designed to function solely within one project, which is in line with the intra-project manner in which Sphinx Docs treats reST substitutions. Note also that Sphinx Docs rst_prolog variables are currently not parsed (if these variables are a source of reST substitutions in your project, then you will need to transfer them to rst_epilog variables). For more details on Sphinx rst_epilog and rst_prolog variables, see the Sphinx configuration docs

Per Project Plugin Settings

All of SphinxRefmate's file list settings can be overridden on an individual sublime text project basis, if required, by placing an entry such as the following, within the 'settings' section of the project's sublime-project file::

"SphinxRefmate": { 
    "intersphinx_map_source_list": [ "/strangely/located/conf.py" ],
    "bib_ref_file_list": [ "../commondata/suite_bibliography.rst" ],
    "rst_epilog_source_list": [ "../commondata/rstepilog_include.py" ],
    "cur_proj_intersphinx_map_name": "sqsh"
            }

“cur_proj_intersphinx_map_name”: “mysite”

An additional Sphinx Refmate setting is definable at project level, which is not available in the Default/User settings. This is the cur_project_intersphinx_map_name. This gives Sphinx Refmate an assured way of identifying the current project line within the intersphinx_mapping variable. Note that it is not necessary to implement this setting as Sphinx Refmate has a fairly robust way of working out which intersphinx_mapping line relates to the current project. However, you should definitely set this variable to overcome any errors that Sphinx Refmate might report concerning an inability to identify the current project.

Key Bindings

No key bindings are enabled by default. Plugin key bindings can be edited via Preferences -> Package Settings -> Sphinx Refmate -> Key Bindings, which presents a twin panel of Example/user key bindings. Example key bindings can be copied over to an active key bindings file to enable them, and configured as per user preferences.

Quick Panel Display Key

For lists of ref/doc/term type references, lines in the quick panel will be prefixed by the intersphinx_mapping name of the project being referenced e.g. myproj>. Additionally there may be an asterix prefix e.g. *myproj>, which denotes that the reference belongs to the current project (the one which is currently being edited).

For lists of citation/substitution type references there will be no prefixes. These types of references always come from the current project under edit.

The intersphinx_mapping Variable

SphinxRefmate uses intersphinx_mapping variables, and the objects.inv files to which they point, for the purpose of enabling documentation writers to better manage referencing. An intersphinx_mapping variable which manages cross referencing for three Sphinx Doc projects may look something like this:

intersphinx_mapping = {
    'rug': ('https://rugby.org', ('_build/html/objects.inv', '../commondata/rug_objects.inv')),
    'sqsh': ('https://squash.org', ('_build/html/objects.inv', '../commondata/sqsh_objects.inv')),
    'can': ('https://canasta.org', ('_build/html/objects.inv', '../commondata/canny_objects.inv'))
    }

The ability to provide multiple targets for the inventory, as above, came about with Sphinx Docs v1.3. This is the type of intersphinx_mapping that Sphinx Refmate uses and expects to be defined. Sphinx Refmate only looks for filepath locations of objects.inv files. The Sphinx Intersphinx extension allows for objects.inv files to be found at website locations, but Sphinx Refmate skips any such settings in the intersphinx_mapping variable (the design choice to do this was made with respect to referencing speed). More information on Intersphinx and the intersphinx_mapping variable can be found in the Sphinx Intersphinx Extension Documentation.

Note: If you only work on a single Sphinx Docs project, and don't want to cross reference any others, there is no need to have the Intersphinx extension running. To meaningfully use Sphinx Refmate on such a project you will still need an intersphinx_mapping variable defined.

A Sphinx Refmate supporting intersphinx_mapping variable, for a single non-cross-referencing project, will probably be defined in conf.py and look something like the following:

intersphinx_mapping = {'cpract': ('https://choir.practice.org',
                                  ('_build/html/objects.inv', '../commondata/cpo_objects.inv'))}

objects.inv file management

The Sphinx Doc build process dumps a project's objects.inv file at the build root. For html builds this usually means the _build/html directory. In the above intersphinx_mapping examples you can see that the first location given for the inventory file, in each case, is this standard location. Build directories are regularly cleared however, and they may even be empty when you are merrily working in Sublime Text to edit your source files. In such a case, if you try to activate the objects.inv dependent features of Sphinx Refmate, it will fail.

One effective way to ensure that Sphinx Refmate cross referencing is always fully available, is to regularly copy a project's objects.inv file from the standard location to a safer one. A systemd timer or cron job could be set up to do this. In these safer locations (such as ../commondata in the above examples) objects.inv files will be more permanently available.

Some issues with cross-project Sphinx Doc referencing and the intersphinx_mapping variable

Note: An intersphinx_mapping shortname for a project is a shorthand way for identifying a project which is chosen by the user when setting up the mapping.

Identifying the current project

Sphinx Refmate needs to be able to identify the local Sphinx Doc project in which it is running, and associate this with an entry in the intersphinx_mapping. This is required because often Sphinx Refmate is called upon to provide references for the current project only.

Identifying which Sphinx Doc projects are private (e.g. lan based) or public (e.g. internet based)

Sphinx Refmate needs to understand whether a Sphinx Doc project is private or public because it makes no sense to insert unreachable links to private resources into a public site (for html website builds).

Editing an existing Sphinx Doc project to utilise Sphinx Refmate

Considering what is written above, an existing Sphinx Doc project may need to undergo some slight modifications if its developers want to begin using Sphinx Refmate. The types of modification that may need to happen are:

• Changing or implementing the intersphinx_mapping variable and ensuring it contains robust paths to objects.inv files.
• Changing the 'shortnames' for projects in the intersphinx_mapping so that they accord with notions of private/pubic as discussed. If this is the case then changing all connected references across the reST source files will also be necessary.