diff --git a/src/pulp_docs/mkdocs_macros.py b/src/pulp_docs/mkdocs_macros.py index e392dd0..957d3ce 100644 --- a/src/pulp_docs/mkdocs_macros.py +++ b/src/pulp_docs/mkdocs_macros.py @@ -144,23 +144,6 @@ def _place_doc_files(src_dir: Path, docs_dir: Path, repo: Repo): try: shutil.copytree(src_dir / SRC_DOCS_DIRNAME, docs_dir / "docs") - # [WORKAROUND] for allowing mkdocstrings to find "unexpected packages". - # Also injects __init__.py so references are - # Example: having pulp-cli/pulpcore/cli - # Mostly usefull for pulp-cli, where this kind of organization makes sense. - # It may be worth considering generalizing this treatment, so repos can define - # the packages to be included in mkdocstrings path. - # See: https://mkdocstrings.github.io/python/usage/#using-the-paths-option - if repo.name != "pulpcore" and "pulpcore" in os.listdir(src_dir): - repo_source_path = src_dir.parent - for child in Path(src_dir / "pulpcore").glob("*"): - if child.is_dir(): - Path(child / "__init__.py").touch(exist_ok=True) - shutil.copytree( - src_dir / "pulpcore", - repo_source_path / "pulpcore" / "pulpcore", - dirs_exist_ok=True, - ) except FileNotFoundError: Path(docs_dir / "docs").mkdir(parents=True) @@ -283,10 +266,17 @@ def define_env(env): ) else: repo_or_package_path = repo_or_package.name - # Add to mkdocstring pythonpath code_sources.append(str(source_dir / repo_or_package_path)) + # TODO: remove this. + # Workaround for making "pulpcore/cli/common" from pulp-cli be available as: + # '::: pulpcore.cli.common' (from any markdown) + # This should be a general solution. + shutil.copytree(source_dir / "pulp-cli/pulpcore", source_dir / "pulpcore/pulpcore", dirs_exist_ok=True) + Path(source_dir / "pulpcore/pulpcore/cli/__init__.py").touch(exist_ok=True) + Path(source_dir / "pulpcore/pulpcore/cli/common/__init__.py").touch(exist_ok=True) + env.conf["plugins"]["mkdocstrings"].config["handlers"]["python"][ "paths" ] = code_sources