Skip to main content
`Ctrl`+`K`

#

# Source code for doxysphinx.sphinx

    # =====================================================================================
    #  C O P Y R I G H T
    # -------------------------------------------------------------------------------------
    #  Copyright (c) 2023 by Robert Bosch GmbH. All rights reserved.
    #
    #  Author(s):
    #  - Markus Braun, :em engineering methods AG (contracted by Robert Bosch GmbH)
    # =====================================================================================
    """The sphinx module contains classes that are tied to sphinx or resemble sphinx logic."""

    from pathlib import Path
    from typing import Protocol

    # noinspection PyMethodMayBeStatic,PyUnusedLocal
    from doxysphinx.utils.pathlib_fix import path_resolve

    class DirectoryMapper(Protocol):
        """
        Mapper that will calculate the output file path for an input file.

        In docs-as-code tooling (e.g. sphinx) often files from a source dir
        structure are processed and written to result files in a target dir structure.

        The make this mapping an implementation detail this protocol exists.
        It should be implemented for any special handling in mapping files.
        """

        def __init__(self, sphinx_source_dir: Path, sphinx_output_dir: Path):
            """
            Protocol for a directory mapper constructor.

            :param sphinx_source_dir: the sphinx source directory
            :param sphinx_output_dir: the sphinx output directoryS
            """

        def map(self, path: Path) -> Path:
            """Calculate the path in output for a given path in input."""
            return Path()

    class SphinxHtmlBuilderDirectoryMapper:
        """
        Mapper that will calculate the output file path for an input file.

        This is based on the logic that the sphinx html builder would use.
        """

        def __init__(self, sphinx_source_dir: Path, sphinx_output_dir: Path):
            """
            Create a sphinx html builder directory mapper.

            This mapper resembles the behavior of the sphinx html build considering path
            handling and copying to output.

            :param sphinx_source_dir: the sphinx source directory
            :param sphinx_output_dir: the sphinx output directoryS
            """
            self.source = sphinx_source_dir
            self.output = sphinx_output_dir

        def map(self, path: Path) -> Path:
            """Calculate the path in output for a given path in input."""
            if path.is_absolute():
                return self._map_absolute(path)
            else:
                return self._map_relative(path)

        def _map_absolute(self, path: Path) -> Path:
            relative_source_path = path.relative_to(path_resolve(self.source))
            output_path = path_resolve(self.output) / relative_source_path
            return output_path

        def _map_relative(self, path: Path) -> Path:
            relative_source_path = path_resolve(path).relative_to(path_resolve(self.source))
            output_path = path_resolve(self.output) / relative_source_path
            return output_path.relative_to(Path.cwd())