Skip to content

Contributing

Jump to bottom
Caden edited this page Apr 11, 2024 · 13 revisions

File Structure

NNsight uses Sphinx to create static documentation from .rst (reStructuredText) files. The source documentation is stored within the nnsight/docs directory of the project. Inside, you'll find:

_static

  • Contains static assets including stylesheets, animations and custom components, and various images.

_templates

  • layout.html extends the base <head> with links to the site's .css files. When the documentation is generated, these links include a version reference so user's browser renders the new .css.
  • ndif_status.html is a script which changes the color/icon of the status icon.

documentation

  • We use the autodoc extension to generate documentation from docstrings in the source code. On each page, you'll find automodule "directives" with references to NNsight source files.

notebooks

  • features contains notebook tutorials for core NNsight features.
  • tutorials contains notebooks for the tutorials section.

conf.py

  • The build configuration file contains configs for customizing Sphinx input and output behavior. See Documentation Configs for more.

index.rst

  • Like index.html, this is the default page for the website. We use the raw directive to use html directly within .rst files.

Installing and Building Documentation

Run pip install -r requirements.txt from the nnsight/docs directory. This installs the list of requirements from here.

To build the documentation, run make dirhtml from the docs/source directory. This will create a docs/build/dirhtml directory containing the generated html. You can see your changes live by starting a python server python3 -m http.server from the dirhtml directory.

If you would like changes to be reflected on the actual website, clone the ndif-website repository. Then, copy the files from docs/build/dirhtml into the public folder inside ndif-website.

Documentation Configs

conf.py is a configuration file for the Sphinx documentation builder.

extensions is a list of extensions which enable special features in our documentation. Two notable extensions are:

  • sphinx.ext.napoleon for automatically generating documentation from NumPy and Google style docstrings.
  • nbsphinx for automaticaly rendering Jupyter notebooks as html output.

html_context adds variables that are accessible across all html templates.

Our documentation uses the PyData Theme. Theme specific settings are under html_theme_options. You can read more in the PyData User Guide.

Example: Adding a new tutorial

Let's walk through adding a new tutorial to the documentation.

Create a Jupyter notebook. The first cell of the notebook should be a markdown cell containing the title of the notebook as an H1 tag. This header will be rendered as the name of the notebook whenever it's referenced in the documentation.

Add your content to the notebook. nbsphinx will render the output cells of the notebook, so you can run all and retain interactive graphs and components in the browser.

Copy the notebook to docs/source/notebooks/tutorials. The notebook will automatically be added to the filetree under tutorials. To understand why, let's look at some snippets from tutorials.rst.

.. toctree::
   :glob:
   :maxdepth: 1

   notebooks/tutorials/*

.. :: indicates a directive, or a command for reStructuredText to interpret a block of context in a certain way. Specifically, the .. toctree:: directive links documents in a hierarchical format. The :glob: argument tells sphinx to render all files in the list of available documents.

.. grid-item-card:: 
  :link: notebooks/tutorials/sae.ipynb
  :class-card: code-surface
  :class-body: code-surface

  .. raw:: html

      <div class="d-flex align-items-center">
        <img src="..." class="img-fluid" style="max-width: 50px; margin-right: 20px;">
        <div>
            <h5 class="code-surface card-title">Dictionary Learning</h5>
            <p class="code-surface card-text">Sparse autoencoders</p>
        </div>
      </div>

This directive is from the Sphinx Design extension. Sphinx Design offers a collection of theme specific bootstrap components. Here, we have a grid item containing the raw directive. This allows us to customize the content of our grid item using html. Note that you'll have to add another grid item to have your tutorial appear as a card on the main page.

Now that we've added a notebook, navigate to docs and run make dirhtml with Sphinx and other requirements installed on your system. If you notice your changes aren't appearing, run make clean to clear the build directory and run make dirhtml again. You can view your changes live by running python3 -m http.server from the dirhtml directory.

Finally, copy the files over ndif-website/public and commit on both repositories.

Example: Changing a header link

The header, and most components that persist across all pages, are configured by the theme. You can change these settings under conf.py.

Inside of conf.py, edit the icon_links value under html_theme_options.

{
  "name": "Discord",
  "url": "YOUR LINK",
  "icon": "fa-brands fa-discord",
},

Like before, run make dirhtml and optionally view your changes on a local server before committing.

Example: Changing the content on a page

Let's add a link to some other website on the getting started page, start.rst. Take note of a couple quirks of reStructuredText.

Getting Started
===============

Titles and section headings should be underlines by certain characters. The number of characters used in the underline should be the same length as the title, or the rst parser will yell at you. See basics for more.

.. code-block:: console
  :example-argument:

  pip install nnsight

Directives MUST have a line break under them before the start of their content or they will not render. This goes for arguments as well.

Now, to add a link we'll simply update the content and include an inline tag. See more in this guide

**NNsight** (/ɛn.saɪt/) is a package for the interpreting and...

You should also check out this link: `example link <http://example.com>`_

Finally, run make dirhtml and optionally view your changes on a local server before committing.

Clone this wiki locally