Public and internal documentation

The documentation is published as two websites built from this single source tree:

  • Public site: readable by anyone. Internal content is removed at build time and is not present in the public HTML.

  • Internal site: readable after signing in with an @nyu.edu Google account. It contains the full content, public and internal.

As a contributor you write everything in the same files. You only mark which parts are internal. The build produces the two sites automatically.

How the split works

The site is built twice from the same sources:

sphinx-build -b html docs/source _build/public                # public
sphinx-build -b html -t internal docs/source _build/internal  # internal

The -t internal tag switches on the internal content. In the public build, anything marked internal is excluded from the HTML and from the search index.

Warning

Never rely on CSS or JavaScript to hide private text. Only the two methods below are safe, because the public HTML then physically does not contain the text. The repository itself is private, which protects the source; the split controls what appears on the public website.

Marking part of a page as internal

Wrap the private part in an only directive with the internal tag. Everything indented under the directive appears on the internal site only. Text before and after it stays public, so a page can be mostly public with a private section in the middle.

Public introduction that everyone can read.

.. only:: internal

   Internal note: vendor phone number, door code, or an unpublished
   procedure. This block is absent from the public site.

Public text continues here.

Making a whole page internal

Give the page a file name containing internal-only, or place it in a folder named internal. Either naming is excluded from the public build:

docs/source/8-meg-operations/vendor-contacts-internal-only.rst   (excluded)
docs/source/8-meg-operations/internal/passwords.rst              (excluded)

Then reference the page from a toctree that is itself wrapped in only, so the public build does not warn about a missing document:

.. only:: internal

   .. toctree::
      :maxdepth: 1

      internal/passwords

Previewing your change

Push your branch. GitHub Actions builds both variants and deploys previews:

https://<branch>.neurowaves-docs.pages.dev            (public preview)
https://<branch>.neurowaves-docs-internal.pages.dev   (internal preview)

Check that your internal content is present on the internal preview and absent from the public preview. The build also runs an automated leak check and fails if internal content reaches the public output.

Moving between the two sites

Each public page shows an NYU internal docs (login) link that opens the same page on the internal site. Each internal page shows a banner with a link back to the public version. You do not need to add these links yourself; they are inserted automatically during the build.

Note

A page that exists only on the internal site has no public counterpart, so its back link would land on a missing page. That is expected. Only use fully internal pages for content that should never be public.