Sphinx Integration

Integration with the documentation module Sphinx is possible out of the box using sasdocs. If you are not already familiar with sphinx, please follow the quick-start tutorial before continuing.

Setting up conf.py

In the conf.py generated by sphinx in the source folder, add the sasdocs.sphinx extention to the list of extentions that can be accessed by sphinx.

# -- 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 = ['sphinx.ext.autodoc', 'sphinx.ext.coverage', 'sphinx.ext.napoleon', 'sasdocs.sphinx']

master_doc = 'index'

Using the extension

The sasdocs sphinx extention has two parts, a parser and a directive.

Sphinx file parser

Adding the extension to conf.py will allow any .sas file found in the source folder or below to be referenced in the TOC tree. This will then be parsed into a doctree and be exportable in any format. SAS programs should be referenced by the file name without the .sas extension.

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   sasprogram1
   sasprogram2
   sasprogram3

Only .sas files found in the source folder or deeper can be parsed directly from the TOC tree directive. To reference SAS files outside of the source directory you can use the sasinclude directive.

sasinclude directive

Any .rst file in your source directory can call the sasinclude directive which will parse the passed SAS file or all SAS files found in the folder and return the result at the point that the directive is called.

.. This will parse sasprogram1.sas and return the result.
.. sasinclude:: ..\sasprograms\sasprogram1.sas

.. This will parse all programs in the ..\sasprograms directory and return the results here.
.. sasinclude:: ..\sasprograms\

sasmacroinclude directive

Similarly to the sasinclude directive the sasmacroinclude directive can be called from any .rst file. It will generate a macro index displaying the arguments and documentation for all the SAS macros found in the defined folder/file.

.. This will create a macro index for all .sas files in the ..\sasprograms directory
.. sasmacroinclude:: ..\sasprograms\

Example

The following is an example for setting up a simple SAS code index in your sphinx documentation. Given a project folder structure like

project
├───sascode
│       macro_1.sas
│       macro_2.sas
│       simple_1.sas
├───docs/source
|       conf.py
|       index.rst
|       mainDocumentation.rst
|       subDocumentation.rst
|       sasIndex.rst

Having added sasdocs.sphinx to the extensions section of conf.py, we simply need to add a sasIndex.rst stub file that calls our sasinclude directive.

.. sasIndex.rst
SAS Index
#########

.. sasinclude:: ..\..\sascode

We also update our index.rst to include this new stub file.

.. index.rst
Example project documentation
=============================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   mainDocumentation
   subDocumentation
   sasIndex

The final structure of our project will be

project
├───sascode
│       macro_1.sas
│       macro_2.sas
│       simple_1.sas
├───docs/source
|       conf.py
|       index.rst
|       mainDocumentation.rst
|       subDocumentation.rst
|       sasIndex.rst

And any SAS files added into the sascode folder will be automatically documented into our sasIndex whenever the sphinx documentation is built.