.. role:: raw-html(raw)
   :format: html

------------------------------------
Public and internal documentation
------------------------------------

.. contents::
   :local:
   :depth: 2

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:

.. code-block:: bash

   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.

.. code-block:: rst

   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:

.. code-block:: text

   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:

.. code-block:: rst

   .. only:: internal

      .. toctree::
         :maxdepth: 1

         internal/passwords

Previewing your change
======================

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

.. code-block:: text

   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.