Building Docs

GS Quant uses Sphinx to generate Python API documentation automatically from the source code. Developers can run Sphinx locally in order to build and view GS Quant documentation.

Documentation Site

The GS Quant documentation site renders the output from the Sphinx generator. The API documentation in this site lives in the /docs folder within the project.

When you have finished writing your Python function, add it to the relevant section in the docs folder, by updating gs_quant/docs/timeseries.rst and updating or creating a new reStructuredText file (.rst). See example:

Title
-------

.. currentmodule:: gs_quant.package.module

.. autosummary::
   :toctree: functions

   func_1
   func_2

The currentmodule directive locates the Python module within the RST file. The autosummary directive along with the :toctree: functions directive automatically generates documentation for the listed functions. For more details on how to use reStructuredText with Sphinx see the following cheatsheet.

Building Docs

Navigate to the docs folder via your console, and run the documentation generator as follows to build the HTML output:

gs_quant\docs>make html

This will create output under the docs/_build folder. To clean the existing docs first, run the following:

gs_quant\docs>make clean

If you added a new function, Sphinx will automatically create a file for it under gs_quant/docs/functions. Open the file and update the header to match the following:

function_name
==================================

.. currentmodule:: gs_quant.package.module

.. autofunction:: function_name

We remove the package from the title to make the documentation cleaner. If you can find a way to do this automatically, let us know! The output files are under gs_quant/docs/_build. Open index.html to view your function docs!

Related Content