docs: reorganize table of concepts and getting started page

docs/README.md

@@ -0,0 +1,38 @@
+# Documentation
+
+## Building the Documentation
+
+1. Build the documentation:
+
+   ```console
+   make -C docs/source doc
+   ```
+
+   The HTML is created in the `docs/source/html` directory.
+
+## Style Conventions
+
+- When to use garak, Garak, and ``garak``?
+
+  - The project is named garak.
+    Type it in lowercase and no styling when you refer to the project or the Python package.
+    We'll add to this list as more circumstances are discovered.
+    This plain-text presentation should be the most frequent use.
+
+    Can you start a sentence with garak?
+    Yes.
+
+    Should you?
+    Problably not.
+    Only start with garak if rephrasing the sentence introduces passive voice or the sentence becomes awkward.
+
+  - The command is ``garak``.
+    If the context is to instruct the reader to run the ``garak`` command, then style it as inline code.
+
+  - In a heading, it's Garak with an uppercase G because it's a heading.
+
+## Publishing the Documentation
+
+Tag the commit to publish with `docs-v<semver>`.
+
+To avoid publishing the documentation as the latest, ensure the commit has `/not-latest` on a single line, tag that commit, and push to GitHub.

docs/source/basic.rst

@@ -1,5 +1,5 @@
-Top-level concepts in ``garak``
-===============================
+Key Concepts and Classes
+========================
 
 What are we doing here, and how does it all fit together?
 Our goal is to test the security of something that takes prompts
@@ -65,4 +65,4 @@ doing the final evaluation
    :members:
    :undoc-members:
    :show-inheritance:
-   :no-index:
+   :no-index:

docs/source/index.rst

@@ -1,7 +1,7 @@
-Welcome to the garak reference documentation
-============================================
+Garak Reference Documentation
+=============================
 
-**garak** is an LLM vulnerability scanner, `<https://garak.ai>`_.
+Garak is an LLM vulnerability scanner, `<https://garak.ai>`_.
 It uses a huge range of probes to examine and query a large language model, simulating
 attacks, and uses a range of detectors on the model's outputs to see if the model was
 vulnerable to any of those attacks.
@@ -26,71 +26,51 @@ Check out the :doc:`usage` section for further information, including :ref:`inst
    mail `[email protected] <mailto:[email protected]>`_ or drop us a note on `Discord <https://discord.gg/uVch4puUCs>`_.
    Thank you!
 
-Contents
---------
-
-
-Using garak
-^^^^^^^^^^^
 
 .. toctree::
+   :caption: Using garak
    :maxdepth: 1
+   :hidden:
 
    how
    usage
-   reporting
-   FAQ <https://github.com/NVIDIA/garak/blob/main/FAQ.md>
-
-Advanced usage
-^^^^^^^^^^^^^^
-
-.. toctree::
-   :maxdepth: 1
-
    configurable
    cliref
+   reporting
    translation
    ascii_smuggling
-
-Code reference
-^^^^^^^^^^^^^^
+   FAQ <https://github.com/NVIDIA/garak/blob/main/FAQ.md>
 
 .. toctree::
+   :caption: Reference
    :maxdepth: 1
+   :hidden:
 
    basic
    attempt
+   buffs
    cli
    command
-   exception
-   interactive
-   langservice
-   payloads
-   _config
-   _plugins
-
-
-
-Plugin structure
-^^^^^^^^^^^^^^^^
-
-.. toctree::
-   :maxdepth: 1
-
-   buffs
    detectors
    evaluators
+   exception
    generators
    harnesses
+   interactive
+   langservice
+   payloads
    probes
    report
+   _config
+   _plugins
 
 
-Building further
-^^^^^^^^^^^^^^^^
-
 .. toctree::
+   :caption: Extending and Contributing
    :maxdepth: 1
+   :hidden:
 
    extending
+   extending.generator
+   extending.probe
    contributing

docs/source/install.rst

@@ -0,0 +1,26 @@
+..  headings: = - ^ "
+Installation
+============
+
+.. _installation:
+
+garak is a command-line tool.
+It is developed in Linux and MacOS.
+
+Installing with pip
+---------------------
+
+.. code-block:: console
+
+   $ python3 -m pip install garak
+
+
+Installing the Development Version
+----------------------------------
+
+The version of garak is updated periodically.
+To install from source in GitHub, run the following command:
+
+.. code-block:: console
+
+   $ python3 -m pip install -U git+https://github.com/NVIDIA/garak.git@main

docs/source/usage.rst

@@ -1,83 +1,35 @@
-Usage
-=====
+..  headings: = - ^ "
+Getting Started
+===============
 
-.. _installation:
-
-Installation
-------------
-
-``garak`` is a command-line tool. It's developed in Linux and OSX.
-
-Friendly install instructions are at `<https://docs.garak.ai/garak/llm-scanning-basics/setting-up/installing-garak>`_ .
-The instructions below will work, but you might need to be quite familiar with your OS to use them, because they assume some particular pieces of background knowledge.
-
-Standard quick `pip` install
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-To use garak, first install it using pip:
-
-.. code-block:: console
-
-   pip install garak
-
-
-Install development version with `pip`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The standard pip version of ``garak`` is updated periodically. To get a fresher version, from GitHub, try:
-
-.. code-block:: console
-
-    python3 -m pip install -U git+https://github.com/NVIDIA/garak.git@main
+Listing Probes
+--------------
 
-
-For development: clone from `git`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-You can also clone the source and run ``garak`` directly. This works fine and is recommended for development.
-
-``garak`` has its own dependencies. You can to install ``garak`` in its own Conda environment:
+By default, when you run a scan, garak runs all the probes on the model and uses the vulnerability detectors recommended by each probe.
+You can list the probes by running the following command:
 
 .. code-block:: console
 
-    conda create --name garak "python>=3.10,<=3.12"
-    conda activate garak
-    gh repo clone NVIDIA/garak
-    cd garak
-    python3 -m pip install -r requirements.txt
-
-OK, if that went fine, you're probably good to go!
-
-
-Running garak
--------------
-
-
-The general syntax is:
+    garak --list_probes
 
-.. code-block:: console
+You can limit the probes to run by specifying more arguments.
 
-    garak <options>
+For example, you can specify ``--probes promptinject`` to run only the `PromptInject <https://github.com/agencyenterprise/promptinject>`_ framework's methods. for example.
+You can also specify specific probes instead of a probe family such as ``--probes lmrc.SlurUsage`` to probe a model for generating slurs based on the `Language Model Risk Cards <https://arxiv.org/abs/2303.18190>`_ framework.
 
-``garak`` needs to know what model to scan, and by default, it'll try all the probes it knows on that model, using the vulnerability detectors recommended by each probe. You can see a list of probes using:
+Running a Scan
+--------------
 
-.. code-block:: console
+To run a scan, you must specify at least the service to scan with the ``--model_type`` argument, such as ``openai``, ``huggingface``, or ``nim``.
+In most cases, you will also specify the model to scan with the ``--model_name`` argument, such as ``gpt-3.5-turbo``, ``meta/llama-3.1-8b-instruct``, and so on.
 
-    garak --list_probes
+For example, to run a scan on the Hugging Face version of GPT2, use ``--model_type huggingface`` and ``--model_name gpt2``.
 
-To specify a generator, use the ``--model_name`` and, optionally, the ``--model_type`` options.
-Model name specifies a model family/interface; model type specifies the exact model to be used.
-The "Intro to generators" section below describes some of the generators supported.
-A straightfoward generator family is Hugging Face models; to load one of these, set ``--model_name`` to ``huggingface`` and ``--model_type`` to the model's name on Hub (e.g. "RWKV/rwkv-4-169m-pile").
-Some generators might need an API key to be set as an environment variable, and they'll let you know if they need that.
+Some hosted models can require an API key to be set as an environment variable.
+If you do not set the associated environment variable, garak stops the scan and reports the required variable name.
 
-``garak`` runs all the probes by default, but you can be specific about that too.
-``--probes promptinject`` will use only the `PromptInject <https://github.com/agencyenterprise/promptinject>`_ framework's methods, for example.
-You can also specify one specific plugin instead of a plugin family by adding the plugin name after a ``.``; for example, ``--probes lmrc.SlurUsage`` will use an implementation of checking for models generating slurs based on the `Language Model Risk Cards <https://arxiv.org/abs/2303.18190>`_ framework.
-
-
-Examples
-^^^^^^^^
+Sample Scans
+------------
 
 Probe ChatGPT for encoding-based prompt injection (OSX/\*nix) (replace example value with a real OpenAI API key):
 
@@ -87,7 +39,7 @@ Probe ChatGPT for encoding-based prompt injection (OSX/\*nix) (replace example v
     garak --model_type openai --model_name gpt-3.5-turbo --probes encoding
 
 
-See if the Hugging Face version of GPT2 is vulnerable to DAN 11.0:
+Determine if the Hugging Face version of GPT2 is vulnerable to DAN 11.0:
 
 .. code-block:: console