From 5db3e9b02734f1efe6b962d5f55147fdd515189a Mon Sep 17 00:00:00 2001 From: William Jamieson Date: Mon, 20 Jun 2022 14:33:19 -0400 Subject: [PATCH] Change to tab layout for pyproject.toml vs setup.cfg (#1155) * Change to tab layout for pyproject vs setup.cfg * Update changes --- CHANGES.rst | 2 +- docs/asdf/extending/extensions.rst | 20 +++++++++-------- docs/asdf/extending/legacy.rst | 18 ++++++++------- docs/asdf/extending/resources.rst | 36 +++++++++++++++++------------- docs/conf.py | 2 +- pyproject.toml | 1 + 6 files changed, 44 insertions(+), 35 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index c5f74a557..12d395d69 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -5,7 +5,7 @@ The ASDF Standard is at v1.6.0 - Overhaul of the ASDF documentation to make it more consistent and readable. [#1142, #1152] - Update deprecated instances of `abstractproperty` to `abstractmethod` [#1148] -- Move build configuration into `pyproject.toml` [#1149] +- Move build configuration into `pyproject.toml` [#1149, #1155] 2.12.0 (2022-06-06) ------------------- diff --git a/docs/asdf/extending/extensions.rst b/docs/asdf/extending/extensions.rst index 080b8331e..3d07a282e 100644 --- a/docs/asdf/extending/extensions.rst +++ b/docs/asdf/extending/extensions.rst @@ -253,18 +253,20 @@ We'll assume that method is located in the module ``asdf_foo_extension.integrati Next, in the package's ``pyproject.toml``, define a ``[project.entry-points]`` section (or ``[options.entry_points]`` in ``setup.cfg``) that identifies the method as an ``asdf.extensions`` entry point: -.. code-block:: toml +.. tab:: pyproject.toml - # pyproject.toml - [project.entry-points] - 'asdf.extensions' = { asdf_foo_extension = 'asdf_foo_extension.integration:get_extensions' } + .. code-block:: toml -.. code-block:: ini + [project.entry-points] + 'asdf.extensions' = { asdf_foo_extension = 'asdf_foo_extension.integration:get_extensions' } - # setup.cfg - [options.entry_points] - asdf.extensions = - asdf_foo_extension = asdf_foo_extension.integration:get_extensions +.. tab:: setup.cfg + + .. code-block:: ini + + [options.entry_points] + asdf.extensions = + asdf_foo_extension = asdf_foo_extension.integration:get_extensions After installing the package, the extension should be automatically available in any new Python session. diff --git a/docs/asdf/extending/legacy.rst b/docs/asdf/extending/legacy.rst index b59e190a9..bf2409c75 100644 --- a/docs/asdf/extending/legacy.rst +++ b/docs/asdf/extending/legacy.rst @@ -881,17 +881,19 @@ containing your schema files to the pytest section of your project's build confi (``pyproject.toml`` or ``setup.cfg``). If you do not already have such a file, creating one with the following should be sufficient: -.. code:: toml +.. tab:: pyproject.toml - # pyproject.toml - [tool.pytest.ini_options] - asdf_schema_root = 'path/to/schemas another/path/to/schemas' + .. code-block:: toml -.. code:: ini + [tool.pytest.ini_options] + asdf_schema_root = 'path/to/schemas another/path/to/schemas' - # setup.cfg - [tool:pytest] - asdf_schema_root = path/to/schemas another/path/to/schemas +.. tab:: setup.cfg + + .. code-block:: ini + + [tool:pytest] + asdf_schema_root = path/to/schemas another/path/to/schemas The schema directory paths should be paths that are relative to the top of the package directory **when it is installed**. If this is different from the path diff --git a/docs/asdf/extending/resources.rst b/docs/asdf/extending/resources.rst index a26c83e01..63bf63f1b 100644 --- a/docs/asdf/extending/resources.rst +++ b/docs/asdf/extending/resources.rst @@ -193,17 +193,19 @@ instance: Then in ``pyproject.toml``, define an ``[project.entry-points]`` section (or ``[options.entry_points]`` in ``setup.cfg``) that identifies the method as an ``asdf.resource_mappings`` entry point: -.. code-block:: toml +.. tab:: pyproject.toml - # pyproject.toml - [project.entry-points] - 'asdf.resource_mappings' = { asdf_foo_schemas = 'asdf_foo_schemas.integration:get_resource_mappings' } + .. code-block:: toml -.. code-block:: ini + [project.entry-points] + 'asdf.resource_mappings' = { asdf_foo_schemas = 'asdf_foo_schemas.integration:get_resource_mappings' } - # setup.cfg - [options.package_data] - * = *.yaml +.. tab:: setup.cfg + + .. code-block:: ini + + [options.package_data] + * = *.yaml After installing the package, it should be possible to load one of our schemas in a new session without any additional setup: @@ -221,17 +223,19 @@ YAML files. There are multiple ways to accomplish this, but one easy option is to add a ``[tool.setuptools.package-data]`` section to ``pyproject.toml`` (or ``[options.package_data]`` in ``setup.cfg``) requesting that all files with a ``.yaml`` extension be installed: -.. code-block:: toml +.. tab:: pyproject.toml + + .. code-block:: toml + + [tool.setuptools.package-data] + '*' = ['*.yaml'] - # pyproject.toml - [tool.setuptools.package-data] - '*' = ['*.yaml'] +.. tab:: setup.cfg -.. code-block:: ini + .. code-block:: ini - # setup.cfg - [options.package_data] - * = *.yaml + [options.package_data] + * = *.yaml Entry point performance considerations -------------------------------------- diff --git a/docs/conf.py b/docs/conf.py index 6aa4bf952..62f8ab09e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -141,7 +141,7 @@ man_pages = [("index", project.lower(), project + " Documentation", [author], 1)] sys.path.insert(0, os.path.join(os.path.abspath(os.path.dirname("__file__")), "sphinxext")) -extensions += ["example", "sphinx_asdf"] +extensions += ["example", "sphinx_asdf", "sphinx_inline_tabs"] def setup(app): diff --git a/pyproject.toml b/pyproject.toml index ffc86c859..f3caefa23 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -39,6 +39,7 @@ docs = [ 'sphinx-asdf', 'sphinx-astropy', 'sphinx-rtd-theme', + 'sphinx-inline-tabs', 'toml', ] tests = [