mkdocs-header-dropdown 0.1.0__tar.gz

mkdocs_header_dropdown-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2024-11-12
+
+### Added
+- Initial release of mkdocs-header-dropdown plugin
+- Support for configurable dropdown menus in MkDocs Material theme header
+- Multiple dropdown menus support
+- Optional icon support for dropdowns
+- Configurable links with text, URL, and target attributes
+- Hover and click interactions
+- Responsive design
+- Dark/light mode compatibility
+- Comprehensive documentation (README, QUICKSTART, USAGE, DEPLOYMENT)
+- Example templates for header integration
+
+### Features
+- Plugin configuration via mkdocs.yml
+- Jinja2 template integration
+- Material theme CSS variable support
+- No external dependencies beyond MkDocs
+
+[0.1.0]: https://github.com/your-org/mkdocs-header-dropdown/releases/tag/v0.1.0

mkdocs_header_dropdown-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,153 @@
+# Contributing to MkDocs Header Dropdown Plugin
+
+Thank you for your interest in contributing to the MkDocs Header Dropdown Plugin!
+
+## How to Contribute
+
+### Reporting Issues
+
+If you find a bug or have a feature request:
+
+1. Check if the issue already exists in [GitHub Issues](https://github.com/cms-cat/mkdocs-header-dropdown/issues)
+2. If not, create a new issue with:
+   - Clear title and description
+   - Steps to reproduce (for bugs)
+   - Expected vs actual behavior
+   - MkDocs and plugin versions
+   - Sample configuration (if applicable)
+
+### Submitting Changes
+
+1. **Fork the repository** on GitHub
+
+2. **Clone your fork**:
+   ```bash
+   git clone https://github.com/YOUR-USERNAME/mkdocs-header-dropdown.git
+   cd mkdocs-header-dropdown
+   ```
+
+3. **Create a branch**:
+   ```bash
+   git checkout -b feature/your-feature-name
+   # or
+   git checkout -b fix/your-bug-fix
+   ```
+
+4. **Make your changes**:
+   - Follow the existing code style
+   - Add tests if applicable
+   - Update documentation if needed
+
+5. **Test your changes**:
+   ```bash
+   # Install in development mode
+   pip install -e .
+
+   # Test with a sample MkDocs site
+   cd /path/to/test/site
+   mkdocs build
+   mkdocs serve
+   ```
+
+6. **Commit your changes**:
+   ```bash
+   git add .
+   git commit -m "Add: Brief description of your changes"
+   ```
+
+   Use commit message prefixes:
+   - `Add:` for new features
+   - `Fix:` for bug fixes
+   - `Update:` for improvements to existing features
+   - `Docs:` for documentation changes
+   - `Refactor:` for code refactoring
+
+7. **Push to your fork**:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+8. **Create a Pull Request**:
+   - Go to the original repository
+   - Click "New Pull Request"
+   - Select your fork and branch
+   - Describe your changes
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.7 or higher
+- MkDocs >= 1.4.0
+- Material for MkDocs theme
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/cms-cat/mkdocs-header-dropdown.git
+cd mkdocs-header-dropdown
+
+# Install in development mode
+pip install -e .
+
+# Or with development dependencies (if we add them later)
+pip install -e ".[dev]"
+```
+
+### Testing
+
+To test your changes:
+
+1. Create a test MkDocs site or use an existing one
+2. Install the plugin in development mode
+3. Configure the plugin in `mkdocs.yml`
+4. Run `mkdocs serve` and verify functionality
+5. Test with different configurations
+6. Test with light and dark themes
+
+## Code Style
+
+- Follow PEP 8 Python style guide
+- Use meaningful variable and function names
+- Add docstrings to classes and functions
+- Keep functions focused and small
+- Comment complex logic
+
+## Documentation
+
+When adding new features:
+
+- Update README.md with basic usage
+- Update USAGE.md with detailed examples
+- Add examples to QUICKSTART.md if applicable
+- Update CHANGELOG.md with your changes
+
+## Version Numbering
+
+We follow [Semantic Versioning](https://semver.org/):
+
+- MAJOR version for incompatible API changes
+- MINOR version for new functionality (backwards compatible)
+- PATCH version for bug fixes (backwards compatible)
+
+## Release Process
+
+Maintainers will handle releases:
+
+1. Update version in `pyproject.toml` and `setup.py`
+2. Update CHANGELOG.md
+3. Create a git tag: `git tag -a vX.Y.Z -m "Release vX.Y.Z"`
+4. Push tag: `git push origin vX.Y.Z`
+5. Create GitHub release from tag
+
+## Questions?
+
+Feel free to:
+- Open an issue for questions
+- Start a discussion on GitHub Discussions (if enabled)
+- Contact the maintainers
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

mkdocs_header_dropdown-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 CMS Common Analysis Tools
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mkdocs_header_dropdown-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include QUICKSTART.md
+include USAGE.md
+include CONTRIBUTING.md
+recursive-include mkdocs_header_dropdown/templates *

mkdocs_header_dropdown-0.1.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: mkdocs-header-dropdown
+Version: 0.1.0
+Summary: A MkDocs plugin to add configurable dropdown menus to the Material theme header
+Home-page: https://github.com/cms-cat/mkdocs-header-dropdown
+Author: CMS Common Analysis Tools
+Maintainer: CMS Common Analysis Tools
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cms-cat/mkdocs-header-dropdown
+Project-URL: Repository, https://github.com/cms-cat/mkdocs-header-dropdown
+Project-URL: Issues, https://github.com/cms-cat/mkdocs-header-dropdown/issues
+Project-URL: Documentation, https://github.com/cms-cat/mkdocs-header-dropdown#readme
+Keywords: mkdocs,plugin,dropdown,navigation,material-theme,documentation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Documentation
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Framework :: MkDocs
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mkdocs>=1.4.0
+Requires-Dist: pyyaml
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# MkDocs Header Dropdown Plugin
+
+A MkDocs plugin that adds configurable dropdown menus to the Material theme header. This plugin allows you to create cross-documentation navigation menus that can be shared across multiple documentation sites.
+
+## Installation
+
+### From Source (Local Development)
+
+```bash
+pip install -e /path/to/mkdocs_header_dropdown
+```
+
+### From Git Repository
+
+```bash
+pip install git+https://github.com/cms-cat/mkdocs-header-dropdown.git
+```
+
+## Quick Start
+
+### Option 1: Using a Shared Config (Recommended for Organizations)
+
+If you're part of an organization with shared documentation links:
+
+```bash
+# Add the shared config as a git submodule
+git submodule add https://github.com/your-org/docs-common.git
+```
+
+```yaml
+# mkdocs.yml
+plugins:
+  - search
+  - header-dropdown:
+      config_file: "docs-common/header-dropdown.yml"
+```
+
+### Option 2: Direct Configuration
+
+For standalone projects:
+
+```yaml
+# mkdocs.yml
+plugins:
+  - search
+  - header-dropdown:
+      dropdowns:
+        - title: "Documentation"
+          links:
+            - text: "Getting Started"
+              url: "/getting-started/"
+            - text: "User Guide"
+              url: "/guide/"
+            - text: "API Reference"
+              url: "/api/"
+        - title: "External Links"
+          links:
+            - text: "GitHub Repository"
+              url: "https://github.com/your-org/your-project"
+              target: "_blank"
+```
+
+**That's it!** The plugin automatically provides the necessary templates. No manual template overrides required.
+
+## Configuration Options
+
+### Plugin Configuration
+
+The plugin supports two ways to configure dropdowns, which can be combined:
+
+1. **`config_file`** (string, optional): Load dropdown configuration from a YAML file
+   - Path is relative to the repository root
+   - Useful for sharing configuration across multiple repositories via git submodules
+
+2. **`dropdowns`** (list, optional): Define dropdowns directly in mkdocs.yml
+
+Both sources are merged together, allowing you to extend shared configs with repository-specific dropdowns.
+
+### Dropdown Configuration
+
+Each dropdown in the `dropdowns` list supports:
+
+- `title` (string, required): The text displayed on the dropdown button
+- `icon` (string, optional): Path to an icon image displayed next to the title
+- `links` (list, required): List of links in the dropdown menu
+
+### Link Configuration
+
+Each link in the `links` list supports:
+
+- `text` (string, required): The text displayed for the link
+- `url` (string, optional): The URL the link points to (not needed if using `submenu`)
+- `target` (string, optional): The target attribute (e.g., `_blank` for new tab)
+- `submenu` (list, optional): List of nested links for a submenu (see Nested Dropdowns below)
+
+## Example: Using Shared Config File
+
+For multiple repositories that share the same dropdown configuration (e.g., via git submodule):
+
+**Step 1**: Create a shared config repository with `header-dropdown.yml`:
+```yaml
+dropdowns:
+  - title: "CMS POG Docs"
+    icon: "/assets/CMSlogo_white_nolabel_1024_May2014.png"
+    links:
+      - text: "Analysis Corrections | CrossPOG"
+        url: "https://cms-analysis-corrections.docs.cern.ch/"
+        target: "_blank"
+      - text: "BTV Docs"
+        url: "https://btv-wiki.docs.cern.ch/"
+        target: "_blank"
+```
+
+**Step 2**: Add as git submodule and reference in `mkdocs.yml`:
+```bash
+git submodule add https://github.com/your-org/cms-docs-config.git
+```
+
+```yaml
+plugins:
+  - header-dropdown:
+      config_file: "cms-docs-config/header-dropdown.yml"
+```
+
+## Example: Multiple Dropdowns
+
+```yaml
+plugins:
+  - header-dropdown:
+      dropdowns:
+        - title: "CMS POG Docs"
+          icon: "/assets/cms-logo.png"
+          links:
+            - text: "BTV Docs"
+              url: "https://btv-wiki.docs.cern.ch/"
+              target: "_blank"
+            - text: "JetMet TWiki"
+              url: "https://twiki.cern.ch/twiki/bin/viewauth/CMS/JetMET"
+        - title: "External Resources"
+          links:
+            - text: "GitHub"
+              url: "https://github.com/cms-cat"
+              target: "_blank"
+            - text: "GitLab"
+              url: "https://gitlab.cern.ch/cms-analysis"
+              target: "_blank"
+```
+
+## Example: Nested Dropdowns
+
+Create submenus by using `submenu` instead of `url`:
+
+```yaml
+plugins:
+  - header-dropdown:
+      dropdowns:
+        - title: "Resources"
+          links:
+            - text: "GitHub"
+              url: "https://github.com/example"
+            - text: "Documentation"  # This will show an arrow
+              submenu:
+                - text: "User Guide"
+                  url: "/guide/"
+                  target: "_blank"
+                - text: "API Reference"
+                  url: "/api/"
+                - text: "Tutorials"
+                  url: "/tutorials/"
+```
+
+Nested dropdowns:
+- Show an arrow indicator (▶) automatically
+- Appear to the right on hover
+- Support multiple levels of nesting
+- Work with keyboard navigation
+```
+
+## Features
+
+- **Shared configuration**: Load dropdown config from external YAML files via git submodules
+- **Flexible configuration**: Mix shared configs with repository-specific dropdowns
+- **Nested dropdowns**: Create multi-level submenus with arrow indicators
+- **Multiple dropdown menus**: Support for any number of dropdowns
+- **Configurable icons and titles**: Customize appearance
+- **Hover and click interactions**: User-friendly interactions
+- **Responsive design**: Works on all screen sizes
+- **Theme integration**: Works with Material theme's light and dark modes
+- **Accessible**: Keyboard-friendly navigation
+- **No manual overrides**: Plugin automatically provides necessary templates
+
+## Requirements
+
+- MkDocs >= 1.4.0
+- Material for MkDocs theme
+
+## License
+
+MIT License
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request on GitHub.

mkdocs_header_dropdown-0.1.0/QUICKSTART.md

@@ -0,0 +1,186 @@
+# Quick Start Guide - MkDocs Header Dropdown Plugin
+
+## What This Plugin Does
+
+The `mkdocs-header-dropdown` plugin allows you to add configurable dropdown menus to your MkDocs Material theme header. This is perfect for organizations with multiple documentation sites that need cross-linking navigation.
+
+## Installation & Setup (5 Minutes)
+
+### Step 1: Install the Plugin
+
+```bash
+# For local development
+pip install -e /path/to/mkdocs-header-dropdown-plugin
+
+# OR from Git repository (once published)
+pip install git+https://gitlab.cern.ch/cms-analysis/mkdocs-header-dropdown.git
+```
+
+### Step 2: Add Plugin Configuration
+
+Add this to your `mkdocs.yml`:
+
+```yaml
+plugins:
+  - search
+  - header-dropdown:
+      dropdowns:
+        - title: "CMS POG Docs"
+          icon: "/assets/CMSlogo_white_nolabel_1024_May2014.png"
+          links:
+            - text: "Analysis Corrections | CrossPOG"
+              url: "https://cms-analysis-corrections.docs.cern.ch/"
+              target: "_blank"
+            - text: "BTV Docs"
+              url: "https://btv-wiki.docs.cern.ch/"
+              target: "_blank"
+```
+
+### Step 3: Copy Template Files
+
+```bash
+# Create overrides directory if it doesn't exist
+mkdir -p overrides/partials
+
+# Copy the dropdown template
+cp /path/to/plugin/templates/partials/header-dropdown.html overrides/partials/
+```
+
+If you don't have a custom header already, also copy the header template:
+
+```bash
+cp /path/to/plugin/templates/partials/header.html overrides/partials/
+```
+
+If you DO have a custom header, add this line where you want the dropdown:
+
+```jinja
+{% include "partials/header-dropdown.html" %}
+```
+
+### Step 4: Configure Theme
+
+Make sure your `mkdocs.yml` has:
+
+```yaml
+theme:
+  name: material
+  custom_dir: overrides
+```
+
+### Step 5: Build or Serve
+
+```bash
+# Build the site
+mkdocs build
+
+# Or serve locally
+mkdocs serve
+```
+
+## For This Project (cat-docs)
+
+### Local Development
+
+Use the new local serve script:
+
+```bash
+./serve-local.sh
+```
+
+This script:
+- Uses your locally installed plugin
+- Initializes submodules if needed
+- Generates correction digest
+- Starts the dev server on http://127.0.0.1:8000
+
+### Using Docker
+
+The original `serve.sh` has been updated to work with the plugin:
+
+```bash
+./serve.sh
+```
+
+This script:
+- Mounts the plugin directory into the Docker container
+- Installs the plugin in the container
+- Runs mkdocs serve
+
+## Troubleshooting
+
+### "Plugin is not installed" Error
+
+**Solution**: Make sure you installed the plugin in your current Python environment:
+```bash
+pip install -e /path/to/mkdocs-header-dropdown-plugin
+```
+
+Verify installation:
+```bash
+pip list | grep mkdocs-header-dropdown
+```
+
+### Dropdown Not Showing
+
+**Solution**:
+1. Check that you copied `header-dropdown.html` to `overrides/partials/`
+2. Verify you have `custom_dir: overrides` in your theme config
+3. Make sure your header includes `{% include "partials/header-dropdown.html" %}`
+
+### Submodule Issues
+
+If you get file not found errors related to systematics:
+
+```bash
+git submodule update --init --recursive
+```
+
+## Next Steps
+
+- See [USAGE.md](USAGE.md) for detailed configuration options
+- See [DEPLOYMENT.md](DEPLOYMENT.md) for sharing across projects
+- See [README.md](README.md) for full documentation
+
+## Example Configuration
+
+Here's a complete example with multiple dropdowns:
+
+```yaml
+theme:
+  name: material
+  custom_dir: overrides
+
+plugins:
+  - search
+  - header-dropdown:
+      dropdowns:
+        # Primary dropdown for POG docs
+        - title: "CMS POG Docs"
+          icon: "/assets/cms-logo.png"
+          links:
+            - text: "Analysis Corrections"
+              url: "https://cms-analysis-corrections.docs.cern.ch/"
+              target: "_blank"
+            - text: "BTV Wiki"
+              url: "https://btv-wiki.docs.cern.ch/"
+              target: "_blank"
+            - text: "Muon Wiki"
+              url: "https://muon-wiki.docs.cern.ch/"
+              target: "_blank"
+
+        # Secondary dropdown for tools
+        - title: "Tools"
+          links:
+            - text: "GitLab"
+              url: "https://gitlab.cern.ch/cms-analysis"
+              target: "_blank"
+            - text: "GitHub"
+              url: "https://github.com/cms-cat"
+              target: "_blank"
+```
+
+## Support
+
+- Issues: https://gitlab.cern.ch/cms-analysis/mkdocs-header-dropdown/issues
+- Email: cms-phys-conveners-CAT@cern.ch