feat!: remove support for old style packages

CHANGELOG.adoc

@@ -23,6 +23,8 @@ and this project adheres to https://semver.org/spec/v2.0.0.html[Semantic Version
 === Removed
 
   * The `api.` prefix for commands is no longer supported.
+  * Old style packages without `contents.toml` are no longer supported. The `xml_subdir` and
+    `include_subdir` entries in the package specification file are now ignored.
 
 
 == 0.8.7 (10 Sep 2023)

asciidoxy/document.py

@@ -45,7 +45,6 @@ class Package:
         python_dir:        Directory containing Python code to include in the documentation. This
                                directory will be added to the Python path for documents in this
                                package
-        scoped:            True if this is a new-style, scoped package.
         copy_adoc_src_dir: True if the content of `adoc_src_dir` should be copied to the working
                                directory.
     """
@@ -58,7 +57,6 @@ class Package:
     adoc_image_dir: Optional[Path] = None
     adoc_root_doc: Optional[Path] = None
     python_dir: Optional[Path] = None
-    scoped: bool = False
     copy_adoc_src_dir: bool = True
 
     def __init__(self, name: str):
@@ -90,8 +88,6 @@ def load_from_toml(self, pkg_root: Path, data: Mapping[str, Any]) -> None:
         if python is not None:
             self.python_dir = path_from_toml(python, "dir", pkg_root)
 
-        self.scoped = True
-
 
 class Document:
     """An AsciiDoc document being processed by AsciiDoxy.

asciidoxy/generator/asciidoc.py

@@ -652,11 +652,6 @@ def _find_document(self, file_name: Optional[str],
             rel_file_name: Optional[Path]
             if package_name and file_name:
                 rel_file_name = Path(file_name)
-            elif file_name and not self._context.document.package.scoped:
-                # and not package_name
-                # Deprecated support for old style packages
-                package_name, rel_file_name = self._context.package_manager.find_original_file(
-                    (self._context.document.work_file.parent / file_name).resolve())
             elif file_name:  # and not package_name
                 rel_file_name = self._context.document.resolve_relative_path(file_name)
                 package_name = self._context.document.package.name

asciidoxy/packaging/collect.py

@@ -27,7 +27,6 @@
 import shutil
 import tarfile
 import urllib
-import warnings
 from abc import ABC, abstractmethod
 from pathlib import Path, PurePath
 from typing import Any, Dict, List, Mapping, Optional, Sequence, Type, TypeVar, Union
@@ -91,14 +90,9 @@ class PackageSpec(ABC):
 
     Attributes:
         name: Name of the package.
-        xml_subdir: Subdirectory in the package containing XML descriptions of the API.
-        include_subdir: Subdirectory in the package containing files for inclusion.
     """
     name: str
 
-    xml_subdir: Optional[str] = None
-    include_subdir: Optional[str] = None
-
     def __init__(self, name: str, **kwargs):
         self.name = name
 
@@ -131,11 +125,7 @@ def from_toml(cls: Type[PackageSpecT], name: str, raw_spec: Mapping[str, Any],
         Raises:
             SpecificationError: The specification in TOML is invalid.
         """
-        get = cls._make_getter(name, raw_spec)
-
         spec = cls(name, **init_args)
-        spec.xml_subdir = get("xml_subdir", optional=True)
-        spec.include_subdir = get("include_subdir", optional=True)
         return spec
 
     @staticmethod
@@ -172,26 +162,8 @@ def _make_package(self, package_dir: Path) -> Package:
                     self.name, "Packaged `contents.toml` specifies a "
                     "non-existing adoc root document.")
 
-        elif self.xml_subdir or self.include_subdir:
-            warnings.warn(
-                "Packages without contents.toml are deprecated and will no longer be"
-                " supported from 0.9.0.", FutureWarning)
-            if self.xml_subdir:
-                xml_dir = package_dir / self.xml_subdir
-                if xml_dir.is_dir():
-                    logger.debug(f"{self.name} has XML subdirectory, considering doxygen type")
-                    pkg.reference_type = "doxygen"
-                    pkg.reference_dir = xml_dir
-            if self.include_subdir:
-                include_dir = package_dir / self.include_subdir
-                if include_dir.is_dir():
-                    logger.debug(f"{self.name} has include subdirectory")
-                    pkg.adoc_src_dir = include_dir
         else:
-            raise InvalidPackageError(
-                self.name, "Package does not contain `contents.toml` and package"
-                " specification does not specify the XML or include"
-                " directory.")
+            raise InvalidPackageError(self.name, "Package does not contain `contents.toml`.")
 
         if pkg.reference_dir is None and pkg.adoc_src_dir is None:
             raise InvalidPackageError(self.name, "Package does not contain XML or include files.")

asciidoxy/packaging/manager.py

@@ -99,7 +99,6 @@ def set_input_files(self,
         pkg = Package(Package.INPUT_PACKAGE_NAME)
         pkg.adoc_src_dir = include_dir
         pkg.adoc_root_doc = in_file
-        pkg.scoped = True
 
         if image_dir is not None:
             pkg.adoc_image_dir = image_dir

documentation/Makefile

@@ -33,7 +33,10 @@ $(DOC_BUILD_DIR)/asciidoxy: $(DOC_BUILD_DIR)
 $(DOXYGEN_BUILD_DIR)/asciidoxy: $(DOXYGEN_BUILD_DIR)
 	mkdir -p $(DOXYGEN_BUILD_DIR)/asciidoxy
 
-$(DOXYGEN_BUILD_DIR)/asciidoxy/xml: $(DOXYGEN_BUILD_DIR)/asciidoxy
+$(DOXYGEN_BUILD_DIR)/asciidoxy/contents.toml: contents.toml $(DOXYGEN_BUILD_DIR)/asciidoxy
+	cp $< $@
+
+$(DOXYGEN_BUILD_DIR)/asciidoxy/xml: $(DOXYGEN_BUILD_DIR)/asciidoxy $(DOXYGEN_BUILD_DIR)/asciidoxy/contents.toml
 	. $(BUILD_DIR)/doxygen-$(LATEST_DOXYGEN_VERSION)/activate_run.sh; doxygen
 
 $(CURDIR)/copy: $(ROOT_DIR)/CHANGELOG.adoc
@@ -45,9 +48,12 @@ EXAMPLE_OUTPUTS := $(addprefix $(DOXYGEN_BUILD_DIR)/,$(addsuffix xml,$(EXAMPLE_D
 
 define EXAMPLE_template
 $(DOXYGEN_BUILD_DIR)/$(1): $(DOXYGEN_BUILD_DIR)
-	mkdir -p $(DOXYGEN_BUILD_DIR)/$(1)
+	mkdir -p $$@
+
+$(DOXYGEN_BUILD_DIR)/$(1)/contents.toml: $(1)/contents.toml $(DOXYGEN_BUILD_DIR)/$(1)
+	cp $$< $$@
 
-$(DOXYGEN_BUILD_DIR)/$(1)xml: $(DOXYGEN_BUILD_DIR)/$(1) $(filter-out %.adoc,$(wildcard $(1)/*))
+$(DOXYGEN_BUILD_DIR)/$(1)xml: $(DOXYGEN_BUILD_DIR)/$(1) $(DOXYGEN_BUILD_DIR)/$(1)/contents.toml $(filter-out %.adoc,$(wildcard $(1)/*))
 	. $(BUILD_DIR)/doxygen-$(LATEST_DOXYGEN_VERSION)/activate_run.sh; cd $(1) && OUTPUT_DIR=$(DOXYGEN_BUILD_DIR)/$(1) doxygen
 endef
 

documentation/asciidoxy.toml

@@ -16,8 +16,6 @@
 
 [sources.local]
 type = "local"
-xml_subdir = "xml"
-include_subdir = "adoc"
 
 [packages]
 

documentation/contents.toml

@@ -0,0 +1,7 @@
+[package]
+name = "asciidoxy"
+
+[reference]
+type = "doxygen"
+dir = "xml"
+

documentation/examples/cpp/contents.toml

@@ -0,0 +1,6 @@
+[package]
+name = "cppexamples"
+
+[reference]
+type = "doxygen"
+dir = "xml"

documentation/examples/java/contents.toml

@@ -0,0 +1,6 @@
+[package]
+name = "javaexamples"
+
+[reference]
+type = "doxygen"
+dir = "xml"

documentation/examples/objc/contents.toml

@@ -0,0 +1,6 @@
+[package]
+name = "objcexamples"
+
+[reference]
+type = "doxygen"
+dir = "xml"

documentation/examples/python/contents.toml

@@ -0,0 +1,6 @@
+[package]
+name = "pythonexamples"
+
+[reference]
+type = "doxygen"
+dir = "xml"

documentation/reference/packages.adoc

@@ -63,16 +63,8 @@ types of packages the following key/value pairs are required:
 
 `type`:: The type of the package.
 
-For old-style packages the following key/value pairs are required. For backwards compatibility they
-can always be specified, even for new-style packages. But in case of new-style packages, they are
-ignored. New-style packages use <<_package_content_files>> to specify the contents.
-
-`xml_subdir`:: Subdirectory in the root of the package in which all Doxygen XML files are stored.
-`include_subdir`:: Subdirectory in the root of the package in which all other include files are
-stored.
-
-Packages of type `local` refer to a local directory. They require the following additional key/value
-pairs:
+Packages of type `local` refer to a local directory. They require the following additional 
+key/value pairs:
 
 `package_dir`:: Absolute or relative path to the directory containing the package.
 
@@ -82,8 +74,6 @@ Example:
 ----
 [packages.local_package]
 type = "local"
-xml_subdir = "xml"
-include_subdir = "adoc"
 package_dir = "/path/to/my/package/"
 ----
 
@@ -132,8 +122,6 @@ Example:
 [packages.package1]
 type = "http"
 url_template = "https://example.com/{name}/{version}/{file_name}"
-xml_subdir = "xml"
-include_subdir = "adoc"
 version = "12.3.4"
 login = "asciidoxy"
 password_env = "ASCIIDOXY_PASSWORD"
@@ -174,8 +162,6 @@ Example:
 [sources.remote_server]
 type = "http"
 url_template = "https://example.com/{name}/{version}/{file_name}"
-xml_subdir = "xml"
-include_subdir = "adoc"
 
 [packages]
 

tests/unit/file_builder.py

@@ -84,7 +84,6 @@ def _add_package(self, package_name: str, default_file: Optional[str] = None):
             pkg.adoc_src_dir = self.packages_dir / package_name
             if default_file:
                 pkg.adoc_root_doc = pkg.adoc_src_dir / default_file
-            pkg.scoped = True
             self.package_manager.packages[package_name] = pkg
         return pkg
 

tests/unit/generator/test_generator.py

@@ -642,21 +642,6 @@ def test_cross_document_ref__package_must_be_explicit(file_builder, tdb_single_a
             assert result == ""
 
 
-def test_cross_document_ref__direct_access_to_other_package_for_old_style_packages(
-        file_builder, tdb_single_and_multipage, tdb_warnings_are_and_are_not_errors):
-    file_builder.add_input_file("input.adoc")
-    file_builder.add_package_file("package", "include.adoc")
-    file_builder.package_manager.input_package().scoped = False
-
-    for api in file_builder.apis():
-        result = api.cross_document_ref("include.adoc", link_text="bla")
-        if isinstance(api, GeneratingApi):
-            if tdb_single_and_multipage:
-                assert result == "<<include.adoc#,bla>>"
-            else:
-                assert result == "<<include.adoc#top-include-top,bla>>"
-
-
 def test_cross_document_ref__with_link_text(file_builder, tdb_single_and_multipage):
     file_builder.add_input_file("input.adoc")
     file_builder.add_include_file("includes/other_file.adoc")
@@ -996,27 +981,6 @@ def test_include__package_does_not_exist(file_builder, tdb_warnings_are_and_are_
             assert api.include("the_right_file.adoc", package_name="package-b") == ""
 
 
-def test_include__direct_access_to_other_package_for_old_style_packages(file_builder):
-    input_file = file_builder.add_input_file("input.adoc")
-    file_builder.add_package_file("package-a", "another_file.adoc")
-    file_builder.package_manager.input_package().scoped = False
-
-    for api in file_builder.apis():
-        result = api.include("another_file.adoc")
-        lines = result.splitlines()
-        assert len(lines) == 2
-
-        assert lines[0] == "[#top-another_file-top]"
-
-        assert lines[1].startswith("include::")
-        assert lines[1].endswith("[leveloffset=+1]")
-
-        file_name = input_file.work_dir / lines[1][9:-16]
-        assert file_name.is_file()
-        assert file_name.name == "another_file.adoc"
-        assert file_name.is_absolute()
-
-
 def test_include__with_leveloffset(file_builder):
     file_builder.add_input_file("input.adoc")
     file_builder.add_include_file("includes/another_file.adoc")