docs: updated API and CONTRIBUTING (#645)

* docs: updated API and CONTRIBUTING

* docs: move contributing in nav

* docs: remove venv

* feat: added docs building to nox

* docs: improve description

---------

Co-authored-by: Andrzej Novak <[email protected]>

Author: 0ctagon

CONTRIBUTING.md

@@ -1,18 +1,16 @@
 # Contributing to mplhep
 
-We are happy to accept contributions to `mplhep` via Pull Requests to the GitHub
-repo. To get started fork the repo.
+We are happy to accept contributions to `mplhep` via Pull Requests to the GitHub repo. To get started fork the repo.
 
 ## Bug Reports
 
-Please open an issue.
+Please open an [issue](https://github.com/scikit-hep/mplhep/issues).
 
 ## Installing the development environment
 
-```
+```bash
 python -m pip install --upgrade --editable ".[all]"
 ```
-
 Also conveniently accessible as `bash install.sh`.
 
 ## Pull Requests
@@ -30,35 +28,66 @@ If you would like to make a pull request please:
 
 ### Running the tests
 
-You can run the unit tests (which should be fast!) via the following command.
+You can run the unit tests (which should be fast!) via the following command:
+
+**With  pytest**
 
 ```bash
 pytest --mpl --ignore=tests/test_notebooks.py
 ```
 
-Note: This ignores the notebook tests (which are run via
-[papermill](https://github.com/nteract/papermill) and run somewhat slow. Make
-sure to run the complete suite before submitting a PR
+Note: This ignores the notebook tests (which are run via [papermill](https://github.com/nteract/papermill)) and run somewhat slow.
+
+Make sure to run the complete suite before submitting a PR
 
 ```bash
 python -m pytest -r sa --mpl --mpl-results-path=pytest_results -n 4
 ```
 
+**With  nox**
+
+```bash
+nox -s tests
+```
+
 ### Making a pull request
 
-We follow [Conventional Commit](https://www.conventionalcommits.org/) for commit
-messages and PR titles. Since we merge PR's using squash commits, it's fine if
-the final commit messages (proposed in the PR body) follow this convention.
+We follow [Conventional Commit](https://www.conventionalcommits.org/) for commit messages and PR titles. Since we merge PR's using squash commits, it's fine if the final commit messages (proposed in the PR body) follow this convention.
 
 ### Generating Reference Visuals
 
-If you modified expected outcomes of the tests. New baseline visuals can be
-generated using this command:
+If you modified expected outcomes of the tests. New baseline visuals can be generated using this command:
+
+**With  pytest**
 
 ```bash
  python -m pytest -r sa --mpl -n 4 --mpl-generate-path=tests/baseline
 ```
 
-Only include the actually modified baseline images in your PR! Running `git add
--a` and the like will sometimes result in including images which are visually
-identically but not the same bit-wise.
+**With  nox**
+
+```bash
+ nox -s generate_examples_figures
+```
+
+Only include the actually modified baseline images in your PR! Running `git add -a` and the like will sometimes result in including images which are visually identically but not the same bit-wise.
+
+### Linting and Formatting
+
+We use `pre-commit` to manage code formatting and linting. Make sure to run it before committing your changes:
+
+**With  pre-commit**
+
+```bash
+pre-commit run --all-files
+```
+
+**With  nox**
+
+```bash
+nox -s lint
+```
+
+## Contributing to the documentation
+
+The documentation is built using [MkDocs](https://www.mkdocs.org/) and the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme. To contribute to the documentation, please look at the [`new_docs/CONTRIBUTING_DOC.md`](CONTRIBUTING_DOC.md) file for instructions.

new_docs/CONTRIBUTING.md renamed to new_docs/CONTRIBUTING_DOC.md

@@ -1,25 +1,53 @@
-# Style-Specific Guide Generation
+# Documentation
 
-This directory contains an automated system for generating a single `guide.md` file with tabs for each experiment style from a template.
+The documentation for `mplhep` is built using [MkDocs](https://www.mkdocs.org/) with the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme.
 
-## Overview
+To build the documentation locally, run the following command from the root directory of the repository:
+
+**With MkDocs:**
+
+ Additional requirements for building the docs are listed in `new_docs/requirements_docs.txt` and can be installed via:
+
+```bash
+pip install -r new_docs/requirements_docs.txt
+```
+Then run:
+
+```bash
+mkdocs build   # Builds the documentation into the site/ directory
+mkdocs serve   # Serves the documentation locally
+```
+
+**With Nox:**
+
+```bash
+nox -s docs   # Builds the documentation into the site/ directory
+nox -s docs -- --fast   # Builds the documentation quickly without rendering code blocks (much faster building time)
+nox -s docs -- --serve (--fast)  # Serves the documentation locally
+```
+
+## Style-Specific Guide Generation
+
+This directory contains an automated system for generating the documentation files with tabs for each experiment style from a template.
+
+### Overview
 
 Instead of manually maintaining separate guide files for each experiment style or manually maintaining one file with all the tabs, we use a template-based approach:
 
 1. **Template Files**: `docs/*_template.md` contains the contents with tab placeholders ({{TABS_START}}/{{TABS_END}})
 2. **Generation Script**: `generate_style_guides.py` expands tabs with style-specific code for each experiment
 3. **MkDocs Hook**: `docs_hooks.py` automatically runs the script before each build
-4. **Generated Files**: Single `docs/*.md` without the `_template`, with tabs for CMS, ATLAS, LHCb, ALICE, DUNE, and plothist
+4. **Generated Files**: `docs/*.md` without the `_template`, with tabs for CMS, ATLAS, LHCb, ALICE, DUNE, and plothist
 
-## Files
+### Files
 
 - `docs/*_template.md` - Templates with `{{TABS_START}}/{{TABS_END}}` markers
 - `generate_style_guides.py` - Script to generate guide.md with experiment tabs
 - `docs_hooks.py` - MkDocs hook that runs the generation script automatically
 
-## How It Works
+### How It Works
 
-### Template Structure
+#### Template Structure
 
 The template uses special markers to denote tabbed sections:
 
@@ -42,7 +70,7 @@ The template uses special markers to denote tabbed sections:
 
 This generates tabs for all 6 styles (CMS, ATLAS, LHCb, ALICE, DUNE, plothist).
 
-### Placeholders
+#### Placeholders
 
 Within tabbed sections, these placeholders get replaced per style:
 
@@ -55,7 +83,7 @@ Within tabbed sections, these placeholders get replaced per style:
 - `{{LABEL_CODE_LUMI}}` - Label code with luminosity
 - `{{MAGIC_CODE}}` - mpl_magic() call if needed (ATLAS, ALICE only)
 
-### Generation Script
+#### Generation Script
 
 Run manually:
 ```bash
@@ -66,41 +94,50 @@ python generate_style_guides.py
 python generate_style_guides.py --template my_template.md --output my_output/guide.md
 ```
 
-### Automatic Generation
+#### Automatic Generation
 
 The MkDocs hook automatically runs the generation script before every build:
 
+**With MkDocs:**
+
 ```bash
 mkdocs build   # Guide is generated automatically
 mkdocs serve   # Guide is generated on startup
 ```
 
-## Making Changes
+**With Nox:**
+
+```bash
+nox -s docs   # Guide is generated automatically
+nox -s docs -- --serve   # Guide is generated on startup
+```
+
+### Making Changes
 
-### To update the templates:
+#### To update the templates:
 
 1. Edit `docs/*_template.md`
 2. For content that should be the same across all styles, edit it directly
 3. For content that varies by style, use `{{TABS_START}}` ... `{{TABS_END}}` markers
 4. Test generation: `python generate_style_guides.py`
-5. Build docs: `mkdocs build` or `mkdocs serve`
+5. Build docs via MkDocs or Nox to see changes
 6. `docs/*.md` without the `_template` files will be regenerated automatically
 
-### To add a new style:
+#### To add a new style:
 
 1. Add style configuration to `generate_style_guides.py` in the `STYLES` dict
 2. Add the style name to `STYLE_ORDER` list
 3. Run the generation script
 
-### To modify style-specific code:
+#### To modify style-specific code:
 
 1. Edit the appropriate entry in the `STYLES` dict in `generate_style_guides.py`
 2. Regenerate: `python generate_style_guides.py`
 
-## Example Template Usage
+### Example Template Usage
 
 ```markdown
-### Simple Example
+#### Simple Example
 
 This shows a basic histogram with different styles:
 
@@ -151,7 +188,7 @@ This generates:
 ...
 ```
 
-## Benefits
+### Benefits
 
 1. **Single Source of Truth**: Edit one template, update all style tabs
 2. **Consistency**: All style tabs have identical structure and examples
@@ -160,31 +197,31 @@ This generates:
 5. **Flexible**: Easy to add new styles or modify existing ones
 6. **Clean**: Template is much simpler than manually maintaining all tabs
 
-## Troubleshooting
+### Troubleshooting
 
-### Guide not updating
+#### Guide not updating
 
 Make sure you're editing `docs/*_template.md`.
 
-### Build errors
+#### Build errors
 
 Check that all placeholders in the template are defined in the `STYLES` dict in `generate_style_guides.py`.
 
-### Missing mpl_magic calls
+#### Missing mpl_magic calls
 
 ATLAS and ALICE styles need `mh.mpl_magic(soft_fail=True)` after labels. This is handled automatically via the `MAGIC_CODE` placeholder which includes proper indentation.
 
-### Testing changes
+#### Testing changes
 
 Always test locally before committing:
 ```bash
 python generate_style_guides.py
-mkdocs build
+mkdocs build / nox -s docs
 # Check the generated file
 less docs/guide.md
 ```
 
-### Manual regeneration
+#### Manual regeneration
 
 If the hook doesn't run for some reason:
 ```bash

new_docs/docs/CONTRIBUTING.md

@@ -0,0 +1 @@
+../../CONTRIBUTING.md

new_docs/docs/CONTRIBUTING_DOC.md

@@ -0,0 +1 @@
+../CONTRIBUTING_DOC.md