Resolve merge conflicts and update documentation

- Resolve merge conflicts in pyproject.toml and README.md
- Update pyproject.toml for poetry 2.x build system with docs dependencies
- Add project-specific content to placeholder docs (overview, getting started,
  use cases, FAQ, extending guide, release notes)
- Create v2.10 release notes page required by docs build check
- Add mkdocs build output to .gitignore
- Fix ruff formatting and import sorting issues

Author: jvanderaa

.gitignore

@@ -125,6 +125,7 @@ venv.bak/
 
 # mkdocs documentation
 /site
+/circuit-maintenance-parser/static/
 
 # mypy
 .mypy_cache/

README.md

@@ -79,12 +79,8 @@
 
 __version__ = metadata.version(__name__)
 
-SUPPORTED_PROVIDER_NAMES = [
-    provider.get_provider_type() for provider in SUPPORTED_PROVIDERS
-]
-SUPPORTED_ORGANIZER_EMAILS = [
-    provider.get_default_organizer() for provider in SUPPORTED_PROVIDERS
-]
+SUPPORTED_PROVIDER_NAMES = [provider.get_provider_type() for provider in SUPPORTED_PROVIDERS]
+SUPPORTED_ORGANIZER_EMAILS = [provider.get_default_organizer() for provider in SUPPORTED_PROVIDERS]
 
 
 def init_provider(provider_type=None) -> Optional[GenericProvider]:

circuit_maintenance_parser/__init__.py

@@ -21,15 +21,11 @@
 )
 @click.option(
     "--provider-type",
-    type=click.Choice(
-        [provider.get_provider_type() for provider in SUPPORTED_PROVIDERS]
-    ),
+    type=click.Choice([provider.get_provider_type() for provider in SUPPORTED_PROVIDERS]),
     default="genericprovider",
     help="Provider type.",
 )
-@click.option(
-    "-v", "--verbose", count=True, help="Increase logging verbosity (repeatable)"
-)
+@click.option("-v", "--verbose", count=True, help="Increase logging verbosity (repeatable)")
 def main(provider_type, data_file, data_type, verbose):
     """Entrypoint into CLI app."""
     # Default logging level is WARNING; specifying -v/--verbose repeatedly can lower the threshold.

circuit_maintenance_parser/cli.py

@@ -1,40 +1,15 @@
 # v1.0 Release Notes
 
-!!! warning "Developer Note - Remove Me!"
-    Guiding Principles:
+This document describes all new features and changes in the `1.x` release series. 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).
 
-    - Changelogs are for humans, not machines.
-    - There should be an entry for every single version.
-    - The same types of changes should be grouped.
-    - Versions and sections should be linkable.
-    - The latest version comes first.
-    - The release date of each version is displayed.
-    - Mention whether you follow Semantic Versioning.
+For a complete history of all releases, see the [full changelog](../../release_notes.md).
 
-    Types of changes:
-
-    - `Added` for new features.
-    - `Changed` for changes in existing functionality.
-    - `Deprecated` for soon-to-be removed features.
-    - `Removed` for now removed features.
-    - `Fixed` for any bug fixes.
-    - `Security` in case of vulnerabilities.
-
-
-This document describes all new features and changes in the release `1.0`. 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).
-
-## Release Overview
-
-- Major features or milestones
-- Achieved in this `x.y` release
-- Changes to compatibility with Nautobot and/or other apps, libraries etc.
-
-## [v1.0.0] - 2026-03-05
+## v1.0.2 - 2021-05-05
 
 ### Added
 
-### Changed
+- [#10](https://github.com/networktocode/circuit-maintenance-parser/pull/10) - Added `cli` command to run as a script.
 
-### Fixed
+## v1.0.0 - 2021-04-29
 
-- [#123](https://github.com/networktocode/circuit-maintenance-parser/issues/123) Fixed Tag filtering not working in job launch form.
+Initial release of the circuit-maintenance-parser library with support for parsing circuit maintenance notifications from Network Service Providers using the iCalendar BCOP standard format.

docs/admin/release_notes/version_1.0.md

@@ -0,0 +1,19 @@
+# v2.10 Release Notes
+
+This document describes all new features and changes in the `2.10` release series. 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).
+
+## [v2.10.0 (2026-01-27)](https://github.com/networktocode/circuit-maintenance-parser/releases/tag/v2.10.0)
+
+### Added
+
+- [#330](https://github.com/networktocode/circuit-maintenance-parser/issues/330) - Add support for parsing AWS HTML format maintenance notification emails
+
+### Dependencies
+
+- [#360](https://github.com/networktocode/circuit-maintenance-parser/issues/360) - Updated lxml to include version 6
+- [#361](https://github.com/networktocode/circuit-maintenance-parser/issues/361) - Updated timezonefinder to v8.2.0
+- [#345](https://github.com/networktocode/circuit_maintenance_parser/issues/345) - Updated minimum Python version to 3.10 and upgraded dependencies including pytest (9.0), pylint (4.0), towncrier (25.8), backoff (2.2), and type stubs
+
+### Housekeeping
+
+- [#344](https://github.com/networktocode/circuit-maintenance-parser/issues/344) - Updated test coverage for the codebase

docs/admin/release_notes/version_2.10.md

@@ -2,3 +2,70 @@
 
 Extending the library is welcome, however it is best to open an issue first, to ensure that a PR would be accepted and makes sense in terms of features and design.
 
+## Adding a New Provider
+
+Adding a new `Provider` is straightforward. Here's an example adding support for an imaginary provider, ABCDE, that uses HTML notifications.
+
+### Step 1: Create the Parser
+
+Create a new file `circuit_maintenance_parser/parsers/abcde.py` with your custom parser(s):
+
+```python
+from typing import Dict
+import bs4  # type: ignore
+from bs4.element import ResultSet  # type: ignore
+from circuit_maintenance_parser.parser import Html
+
+class HtmlParserABCDE1(Html):
+    def parse_html(self, soup: ResultSet) -> Dict:
+        data = {}
+        self._parse_bs(soup.find_all("b"), data)
+        self._parse_tables(soup.find_all("table"), data)
+        return [data]
+
+    def _parse_bs(self, btags: ResultSet, data: Dict):
+        ...
+
+    def _parse_tables(self, tables: ResultSet, data: Dict):
+        ...
+```
+
+### Step 2: Create the Provider
+
+Define a new class in `circuit_maintenance_parser/provider.py`:
+
+```python
+class ABCDE(GenericProvider):
+    _processors: List[GenericProcessor] = [
+        CombinedProcessor(data_parsers=[EmailDateParser, HtmlParserABCDE1]),
+    ]
+    _default_organizer = "noc@abcde.com"
+```
+
+The `_processors` attribute is a list of `Processor` instances that use several data `Parsers`. The `_default_organizer` fills the `organizer` attribute if missing from the notification.
+
+### Step 3: Expose the Provider
+
+Update `circuit_maintenance_parser/__init__.py`:
+
+```python
+from .provider import (
+    GenericProvider,
+    ABCDE,
+    ...
+)
+
+SUPPORTED_PROVIDERS = (
+    GenericProvider,
+    ABCDE,
+    ...
+)
+```
+
+### Step 4: Add Tests
+
+- Add parser tests in `tests/unit/test_parsers.py`
+- Add provider/end-to-end tests in `tests/unit/test_e2e.py`
+- Add sample data in `tests/unit/data/abcde/`
+
+You can anonymize IPv4 and IPv6 addresses in test data using `invoke anonymize-ips`.

docs/dev/extending.md

@@ -1 +1,21 @@
 # Frequently Asked Questions
+
+## Q: My provider is not supported. What can I do?
+
+You can extend the library by adding a new provider. See the [Extending the Library](../dev/extending.md) guide for instructions. Pull requests for new providers are always welcome!
+
+## Q: The parser for my provider is returning incorrect data. What should I do?
+
+Please [open an issue](https://github.com/networktocode/circuit-maintenance-parser/issues/new) with the details. If possible, include a sanitized sample of the notification data that is being parsed incorrectly.
+
+## Q: Can I use the LLM-powered parser without a specific provider?
+
+Yes, the LLM-powered parsers are automatically appended after all existing processors for each defined Provider when the appropriate environment variables are set. You can use them with any provider, including the `GenericProvider`.
+
+## Q: How do I check if a maintenance was parsed by an LLM?
+
+Each `Maintenance` object has a `metadata` attribute. Check `maintenance.metadata.generated_by_llm` to determine if LLM parsing was used.
+
+## Q: Where can I get help?
+
+Feel free to swing by the [Network to Code Slack](https://networktocode.slack.com/) (channel `#networktocode`). Sign up [here](http://slack.networktocode.com/) if you don't have an account.

docs/user/faq.md

@@ -8,12 +8,63 @@ To install the library, please follow the instructions detailed in the [Installa
 
 ## First steps with the Library
 
-!!! warning "Developer Note - Remove Me!"
-    What (with screenshots preferably) does it look like to perform the simplest workflow within the library once installed?
+### Parse an iCalendar Notification
 
-## What are the next steps?
+The simplest use case is parsing a standard iCalendar (BCOP) notification:
+
+```python
+from circuit_maintenance_parser import init_provider, NotificationData
+
+# Initialize a generic provider (supports standard iCalendar format)
+provider = init_provider()
+
+# Create notification data from raw iCalendar content
+raw_data = b"""BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Maint Note//https://github.com/maint-notification//
+BEGIN:VEVENT
+SUMMARY:Maint Note Example
+DTSTART;VALUE=DATE-TIME:20151010T080000Z
+DTEND;VALUE=DATE-TIME:20151010T100000Z
+DTSTAMP;VALUE=DATE-TIME:20151010T001000Z
+UID:42
+SEQUENCE:1
+X-MAINTNOTE-PROVIDER:example.com
+X-MAINTNOTE-ACCOUNT:137.035999173
+X-MAINTNOTE-MAINTENANCE-ID:WorkOrder-31415
+X-MAINTNOTE-IMPACT:OUTAGE
+X-MAINTNOTE-OBJECT-ID;X-MAINTNOTE-OBJECT-IMPACT=OUTAGE:circuit-1
+X-MAINTNOTE-STATUS:TENTATIVE
+ORGANIZER;CN="Example NOC":mailto:noone@example.com
+END:VEVENT
+END:VCALENDAR
+"""
+
+data = NotificationData.init_from_raw("ical", raw_data)
+maintenances = provider.get_maintenances(data)
+
+print(maintenances[0].to_json())
+```
+
+### Parse a Provider-Specific Notification
 
-!!! warning "Developer Note - Remove Me!"
-    After taking the first steps, what else could the users look at doing.
+For providers that don't use the standard iCalendar format, initialize a provider-specific instance:
+
+```python
+from circuit_maintenance_parser import init_provider
+
+# Initialize a provider-specific parser (e.g., Zayo)
+zayo_provider = init_provider("zayo")
+```
+
+### Use the CLI
+
+The library also provides a command-line interface:
+
+```bash
+circuit-maintenance-parser --data-file notification.eml --data-type email --provider-type zayo
+```
+
+## What are the next steps?
 
-You can check out the [Use Cases](./lib_use_cases.md) section for more examples.
+You can check out the [Use Cases](./lib_use_cases.md) section for more examples.

docs/user/lib_getting_started.md

@@ -4,13 +4,20 @@ This document provides an overview of the library including critical information
 
 ## Description
 
+`circuit-maintenance-parser` is a Python library that parses circuit maintenance notifications from Network Service Providers (NSPs), converting heterogeneous formats to a well-defined structured format.
+
+Every network depends on external circuits provided by NSPs who interconnect them to the Internet, to office branches or to external service providers such as Public Clouds. These services occasionally require operation windows to upgrade or fix related issues, usually in the form of **circuit maintenance periods**. NSPs generally notify customers of these upcoming events so that customers can take actions to minimize impact.
+
+The challenge is that almost every NSP defines its own maintenance notification format, even though the relevant information is mostly the same. This library parses notification formats from several providers and returns a standardized object struct, making it easier to process them.
+
+The output format follows the [BCOP](https://github.com/jda/maintnote-std/blob/master/standard.md) defined during a NANOG meeting that promotes the usage of the iCalendar format.
 
 ## Audience (User Personas) - Who should use this Library?
 
-!!! warning "Developer Note - Remove Me!"
-    Who is this meant for/ who is the common user of this library?
+- **Network Engineers** who need to automate the processing of circuit maintenance notifications from multiple providers.
+- **Network Operations Center (NOC) teams** who want to standardize how maintenance windows are tracked across different NSPs.
+- **Automation developers** building workflows that need to programmatically consume and act on circuit maintenance notifications.
 
 ## Authors and Maintainers
 
-!!! warning "Developer Note - Remove Me!"
-    Add the team and/or the main individuals maintaining this project. Include historical maintainers as well.
+This library is maintained by [Network to Code](https://www.networktocode.com/). For a full list of contributors, see the [GitHub contributors page](https://github.com/networktocode/circuit-maintenance-parser/graphs/contributors).