Steps

The Steps module contains modular planning steps that encapsulate specific transformation logic. Each step inspects discovery or normalized data and emits plan actions when its conditions are met.

Steps do not execute transformations. They do not access the filesystem. Their sole responsibility is to recognize patterns and express intent declaratively.

This design allows new behaviors to be added by introducing new steps, without modifying the planner core or execution layer. Steps are where domain knowledge becomes explicit, reviewable, and extensible.

dita_package_processor.steps.base

Base interfaces for processing steps.

This module defines the abstract base class used by all processing steps in the DITA Package Processor pipeline.

ProcessingStep

Bases: ABC

Abstract base class for all processing steps.

Each processing step represents a single, isolated transformation applied to a DITA package. Steps are executed sequentially by the pipeline and share state exclusively through the ProcessingContext.

Subclasses must implement the run method.

run(context, logger) abstractmethod

Execute the processing step.

Implementations should perform a single, well-defined operation and must not invoke other steps directly.

Parameters:

Name	Type	Description	Default
context	ProcessingContext	Shared processing context containing package state.	required
logger	Logger	Logger instance scoped to the processor.	required

Raises:

Type	Description
Exception	Implementations may raise exceptions to signal unrecoverable errors.

dita_package_processor.steps.process_maps

Processing step for normalizing non-main DITA maps.

This step performs the following actions:

• Identifies and handles the abstract map.
• Pulls the abstract topic into the main map.
• Numbers remaining maps sequentially.
• Wraps each map's top-level topicrefs under a generated concept topic.

ProcessMapsStep

Bases: ProcessingStep

Normalize non-main DITA maps.

Responsibilities:

1. Detect an abstract map and inject its referenced topic into the renamed main map.
2. Wrap each remaining map under a numbered wrapper concept topic to enforce a deterministic hierarchy.

run(context, logger)

Execute the map normalization step.

Parameters:

Name	Type	Description	Default
context	ProcessingContext	Shared processing context.	required
logger	Logger	Logger instance scoped to the processor.	required

dita_package_processor.steps.refactor_glossary

Step to refactor definition topics into glossentry topics.

RefactorGlossaryStep

Bases: ProcessingStep

Refactor definition topics into DITA glossentry topics.

This step locates a configured definition map, finds a topicref node matching a given navtitle, and transforms each referenced topic into a <glossentry> in place.

All failures in this step are non-fatal by contract. Missing or malformed inputs result in warnings and early return.

run(context, logger)

Execute glossary refactoring.

This method never raises exceptions. All error conditions are logged and treated as non-fatal.

dita_package_processor.steps.remove_index_map

Processing step for resolving and removing the index DITA map.

This step reads index.ditamap, resolves the referenced main map, records its location in the processing context, and then deletes index.ditamap from the package.

RemoveIndexMapStep

Bases: ProcessingStep

Resolve the main map from index.ditamap and remove the index map.

This step: - Reads index.ditamap from the package root - Extracts the referenced main map href - Stores the resolved main map path in the processing context - Deletes index.ditamap from the filesystem

run(context, logger)

Execute the index map resolution step.

Parameters:

Name	Type	Description	Default
context	ProcessingContext	Shared processing context.	required
logger	Logger	Logger instance scoped to the processor.	required

Raises:

Type	Description
FileNotFoundError	If index.ditamap is missing.
ValueError	If the main map href cannot be resolved.

dita_package_processor.steps.rename_main_map

Processing step for renaming the resolved main DITA map.

This step renames the main map resolved from index.ditamap to match the configured DOCX filename stem and records the new path in the processing context.

RenameMainMapStep

Bases: ProcessingStep

Rename the main DITA map to <docx_stem>.ditamap.

This step: - Requires the main map path to already be resolved - Renames the map file on disk - Stores the renamed path in the processing context

run(context, logger)

Execute the main map renaming step.

Parameters:

Name	Type	Description	Default
context	ProcessingContext	Shared processing context.	required
logger	Logger	Logger instance scoped to the processor.	required

Raises:

Type	Description
ValueError	If the main map has not been resolved yet.
FileExistsError	If the target filename already exists.