More documentation cleanup

README.md

@@ -2,80 +2,38 @@
 
 [![PyPI - Version](https://img.shields.io/pypi/v/hatch-jupyter-builder.svg)](https://pypi.org/project/hatch-jupyter-builder)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hatch-jupyter-builder.svg)](https://pypi.org/project/hatch-jupyter-builder)
+[![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch)
 
 ---
 
 This provides a [build hook](https://hatch.pypa.io/latest/config/build/#build-hooks) plugin for [Hatch](https://github.com/pypa/hatch) that adds a build step for use with Jupyter packages.
 
 **Table of Contents**
 
+- [Documentation](#documentation)
 - [Installation](#installation)
 - [License](#license)
 - [Usage and Configuration](#usage_and_configuration)
 - [Local Development](#local_development)
 
+## Documentation
+
+The full documenation is available on [Read The Docs](https://hatch-jupyter-builder.readthedocs.io/en/latest/).
+
 ## Installation
 
 ```console
 pip install hatch-jupyter-builder
 ```
 
-## License
-
-`hatch-jupyter-builder` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
-
-## Usage and Configuration
-
-The [build hook plugin](https://hatch.pypa.io/latest/plugins/build-hook/) name is `jupyter-builder`.
-
-- **_pyproject.toml_**
-
-  ```toml
-  [tool.hatch.build.hooks.jupyter-builder]
-  dependencies = ["hatch-jupyter-builder"]
-  build-function = "hatch_jupyter_builder.npm_builder"
-  ensured-targets = ["foo/generated.txt"]
-  install-pre-commit-hook = true
-
-  [tool.hatch.build.hooks.jupyter-builder.build-kwargs]
-  build_cmd = "build:src"
-  ```
-
-### Options
-
-The only required fields are `dependencies` and `build-function`.
-The build function is defined as an importable string with a module and a function name, separated by a period. The function must accept a
-`target_name` (either "wheel" or "sdist"), and a `version` (either "standard" or "editable") as its only positional arguments. E.g.
-
-- **_builder.py_**
-
-  ```python
-  def build_func(target_name, version):
-      ...
-  ```
-
-Would be defined as `build-function = "builder.build_func"`
-
-The optional `ensured-targets` is a list of expected file paths after building a
-"standard" version sdist or wheel.
-
-The optional `skip-if-exists` is a list of paths whose presence would cause
-the build step to be skipped. This option is ignored in `editable` mode.
-The `ensured-targets` will still be checked, if given.
-
-The optional `build-kwargs` is a set of keyword arguments to pass to the build
-function.
-
-You can also use `editable-build-kwargs` if the parameters should differ
-in editable mode. If only the build command is different, you can use
-`editable_build_cmd` in `build-kwargs` instead.
-
-The optional `install-pre-commit-hook` boolean causes a `pre-commit` hook to be installed during an editable install.
+## Local Development
 
-### Npm Builder Function
+To test this package locally with another package, use the following:
 
-This library provides a convenenice `npm_builder` function which can be
-used to build `npm` assets as part of the build.
+```toml
+[tool.hatch.build.hooks.jupyter-builder]
+dependencies = ["hatch-jupyter-builder@file://<path_to_this_repo>"]
+```
 
 ## Migration
 
@@ -100,11 +58,8 @@ python -m hatch_jupyter_builder.compare_migration <source_dir> <target_dir> sdis
 
 Use `wheel` to compare wheel file contents.
 
-## Local Development
+See the [documentation for more information on migration](https://hatch-jupyter-builder.readthedocs.io/en/latest/source/how_to_guides/index.html) for more details.
 
-To test this package locally with another package, use the following:
+## License
 
-```toml
-[tool.hatch.build.hooks.jupyter-builder]
-dependencies = ["hatch-jupyter-builder@file://<path_to_this_repo>"]
-```
+`hatch-jupyter-builder` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

docs/source/background/index.rst

@@ -8,9 +8,9 @@ as part of their Python packages.
 
 Typical use cases are Jupyter Lab Extensions and Jupyter Widgets.
 
-The ``hatchling`` build backend is part of the ``hatch`` project,
+The ``hatchling`` build backend is part of the `hatch <https://hatch.pypa.io/latest/intro/>`_ project,
 a member of the Python Packaging Authority.  It provides a simple
 build backend that is compliant with the relevant Python Enhancement
 Proposals, but also provides many useful features such as
-``shared-data``, which can be used to provide Jupyter configuration
+`shared-data <https://hatch.pypa.io/latest/plugins/builder/wheel/#options>`_, which can be used to provide Jupyter configuration
 and runtime files.

docs/source/get_started/config.md

@@ -0,0 +1,77 @@
+# Configuration
+
+The [build hook plugin](https://hatch.pypa.io/latest/plugins/build-hook/) name is `jupyter-builder`. The minimal set of options is:
+
+- **_pyproject.toml_**
+
+  ```toml
+  [tool.hatch.build.hooks.jupyter-builder]
+  dependencies = ["hatch-jupyter-builder"]
+  build-function = "hatch_jupyter_builder.npm_builder"
+  ```
+
+Or with all options given:
+
+- **_pyproject.toml_**
+
+  ```toml
+    [tool.hatch.build.hooks.jupyter-builder]
+    dependencies = ["hatch-jupyter-builder"]
+    build-function = "hatch_jupyter_builder.npm_builder"
+    ensured-targets = ["foo/generated.txt"]
+    skip-if-exists = ["foo/generated.txt"]
+    install-pre-commit-hook = true
+
+    [tool.hatch.build.hooks.jupyter-builder.build-kwargs]
+    build_cmd = "build:src"
+
+    [tool.hatch.build.hooks.jupyter-builder.editable-build-kwargs]
+    build_cmd = "build"
+  ```
+
+## Options
+
+### build-function
+
+The build function is defined as an importable string with a module and a function name, separated by a period. The function must accept a
+`target_name` (either "wheel" or "sdist"), and a `version` (either "standard" or "editable") as its only positional arguments. E.g.
+
+- **_builder.py_**
+
+  ```python
+  def build_func(target_name, version):
+      ...
+  ```
+
+Would be defined as `build-function = "builder.build_func"`
+
+### ensured-targets
+
+The optional `ensured-targets` is a list of expected file paths after building a
+"standard" version sdist or wheel.
+
+### skip-if-exsits
+
+The optional `skip-if-exists` is a list of paths whose presence would cause
+the build step to be skipped. This option is ignored in `editable` mode.
+The `ensured-targets` will still be checked, if given.
+
+### build-kwargs
+
+The optional `build-kwargs` is a set of keyword arguments to pass to the build
+function.
+
+### editable-build-kwargs
+
+You can also use `editable-build-kwargs` if the parameters should differ
+in editable mode. If only the build command is different, you can use
+`editable_build_cmd` in `build-kwargs` instead.
+
+### install-pre-commit-hook
+
+The optional `install-pre-commit-hook` boolean causes a `pre-commit` hook to be installed during an editable install.
+
+## Npm Builder Function
+
+This library provides a convenenice `npm_builder` function which can be
+used to build `npm` assets as part of the build. See the [API Docs](npm_builder_function) for more information on usage.

docs/source/get_started/index.rst

@@ -6,4 +6,9 @@ Tutorials. A hands-on introduction to Hatch Jupyter Builder for maintainers.
    :maxdepth: 1
    :caption: Contents:
 
-Coming soon!
+   config
+
+If starting from a new project, use `hatch new "my project name"`, and follow
+along with the prompts.  Then add the appropriate [configuration](./config) for `hatch_jupyter_builder` in your `pyproject.toml` flag.
+
+If migrating from existing project, find the appropriate [how to guides](../how_to_guides).

docs/source/reference/api_docs.rst

@@ -1,6 +1,7 @@
 API Docs
 ========
 
+.. _npm_builder_function:
 
 NPM Builder Function
 --------------------

docs/source/reference/changelog.md

@@ -2,6 +2,50 @@
 
 <!-- <START NEW CHANGELOG ENTRY> -->
 
+## 0.5.3
+
+([Full Changelog](https://github.com/jupyterlab/hatch-jupyter-builder/compare/v0.5.2...c73212c3e88c7fe203df94b8d07100219baa8d89))
+
+### Enhancements made
+
+- Add logging and handle editable npm arg [#41](https://github.com/jupyterlab/hatch-jupyter-builder/pull/41) ([@blink1073](https://github.com/blink1073))
+- Add handling of create_cmdclass [#40](https://github.com/jupyterlab/hatch-jupyter-builder/pull/40) ([@blink1073](https://github.com/blink1073))
+- Handle license file in migration [#37](https://github.com/jupyterlab/hatch-jupyter-builder/pull/37) ([@blink1073](https://github.com/blink1073))
+- Add jupyter_packaging conversion wrapper [#36](https://github.com/jupyterlab/hatch-jupyter-builder/pull/36) ([@blink1073](https://github.com/blink1073))
+
+### Bugs fixed
+
+- Fix command in `install_pre_commit_hook` [#55](https://github.com/jupyterlab/hatch-jupyter-builder/pull/55) ([@jtpio](https://github.com/jtpio))
+- Use version_template for pyproject.toml [#48](https://github.com/jupyterlab/hatch-jupyter-builder/pull/48) ([@blink1073](https://github.com/blink1073))
+- Fix compare script [#35](https://github.com/jupyterlab/hatch-jupyter-builder/pull/35) ([@blink1073](https://github.com/blink1073))
+
+### Maintenance and upkeep improvements
+
+- [pre-commit.ci] pre-commit autoupdate [#53](https://github.com/jupyterlab/hatch-jupyter-builder/pull/53) ([@pre-commit-ci](https://github.com/pre-commit-ci))
+- Fix flake8 v5 compat [#52](https://github.com/jupyterlab/hatch-jupyter-builder/pull/52) ([@blink1073](https://github.com/blink1073))
+- [pre-commit.ci] pre-commit autoupdate [#51](https://github.com/jupyterlab/hatch-jupyter-builder/pull/51) ([@pre-commit-ci](https://github.com/pre-commit-ci))
+- [pre-commit.ci] pre-commit autoupdate [#50](https://github.com/jupyterlab/hatch-jupyter-builder/pull/50) ([@pre-commit-ci](https://github.com/pre-commit-ci))
+- [pre-commit.ci] pre-commit autoupdate [#47](https://github.com/jupyterlab/hatch-jupyter-builder/pull/47) ([@pre-commit-ci](https://github.com/pre-commit-ci))
+- Do not use dev version yet [#46](https://github.com/jupyterlab/hatch-jupyter-builder/pull/46) ([@blink1073](https://github.com/blink1073))
+- [pre-commit.ci] pre-commit autoupdate [#44](https://github.com/jupyterlab/hatch-jupyter-builder/pull/44) ([@pre-commit-ci](https://github.com/pre-commit-ci))
+- Add sphinx docs stub [#42](https://github.com/jupyterlab/hatch-jupyter-builder/pull/42) ([@blink1073](https://github.com/blink1073))
+- [pre-commit.ci] pre-commit autoupdate [#39](https://github.com/jupyterlab/hatch-jupyter-builder/pull/39) ([@pre-commit-ci](https://github.com/pre-commit-ci))
+- Rename migration scripts [#38](https://github.com/jupyterlab/hatch-jupyter-builder/pull/38) ([@blink1073](https://github.com/blink1073))
+
+### Documentation improvements
+
+- Start adding more docs [#45](https://github.com/jupyterlab/hatch-jupyter-builder/pull/45) ([@blink1073](https://github.com/blink1073))
+- Add docs scaffolding [#43](https://github.com/jupyterlab/hatch-jupyter-builder/pull/43) ([@blink1073](https://github.com/blink1073))
+- Add sphinx docs stub [#42](https://github.com/jupyterlab/hatch-jupyter-builder/pull/42) ([@blink1073](https://github.com/blink1073))
+
+### Contributors to this release
+
+([GitHub contributors page for this release](https://github.com/jupyterlab/hatch-jupyter-builder/graphs/contributors?from=2022-06-21&to=2022-08-19&type=c))
+
+[@blink1073](https://github.com/search?q=repo%3Ajupyterlab%2Fhatch-jupyter-builder+involves%3Ablink1073+updated%3A2022-06-21..2022-08-19&type=Issues) | [@jtpio](https://github.com/search?q=repo%3Ajupyterlab%2Fhatch-jupyter-builder+involves%3Ajtpio+updated%3A2022-06-21..2022-08-19&type=Issues) | [@pre-commit-ci](https://github.com/search?q=repo%3Ajupyterlab%2Fhatch-jupyter-builder+involves%3Apre-commit-ci+updated%3A2022-06-21..2022-08-19&type=Issues) | [@welcome](https://github.com/search?q=repo%3Ajupyterlab%2Fhatch-jupyter-builder+involves%3Awelcome+updated%3A2022-06-21..2022-08-19&type=Issues)
+
+<!-- <END NEW CHANGELOG ENTRY> -->
+
 ## 0.5.2
 
 ([Full Changelog](https://github.com/jupyterlab/hatch-jupyter-builder/compare/v0.5.1...979babceb148f3c6a6ff823bacfd88e94b8a0c22))
@@ -16,8 +60,6 @@
 
 [@blink1073](https://github.com/search?q=repo%3Ajupyterlab%2Fhatch-jupyter-builder+involves%3Ablink1073+updated%3A2022-06-20..2022-06-20&type=Issues)
 
-<!-- <END NEW CHANGELOG ENTRY> -->
-
 ## 0.5.1
 
 ([Full Changelog](https://github.com/jupyterlab/hatch-jupyter-builder/compare/v0.5.0...766fcddec85c1ca1d49f806539f9177feadb1f48))

hatch_jupyter_builder/plugin.py

@@ -1,3 +1,6 @@
+import typing as t
+from dataclasses import dataclass, field
+
 from hatchling.builders.hooks.plugin.interface import BuildHookInterface
 
 from .utils import (
@@ -10,6 +13,18 @@
 )
 
 
+@dataclass
+class JupyterBuildConfig:
+    """Build config values for Hatch Jupyter Builder."""
+
+    install_pre_commit_hook: str = ""
+    build_function: t.Optional[str] = None
+    build_kwargs: t.Mapping[str, str] = field(default_factory=dict)
+    editable_build_kwargs: t.Mapping[str, str] = field(default_factory=dict)
+    ensured_targets: t.List[str] = field(default_factory=list)
+    skip_if_exists: t.List[str] = field(default_factory=list)
+
+
 class JupyterBuildHook(BuildHookInterface):
     PLUGIN_NAME = "jupyter-builder"
 
@@ -20,43 +35,38 @@ def initialize(self, version, build_data):
             log.info(f"ignoring target name {self.target_name}")
             return
 
-        should_install_hook = self.config.get("install-pre-commit-hook")
+        config = JupyterBuildConfig(**normalize_kwargs(self.config))  # type: ignore[arg-type]
+
+        should_install_hook = config.install_pre_commit_hook
 
         if version == "editable" and should_install_hook:
             install_pre_commit_hook()
 
-        # Get the configuration options.
-        build_function = self.config.get("build-function")
-        build_kwargs = self.config.get("build-kwargs", {})
-        editable_build_kwargs = self.config.get("editable-build-kwargs")
-        ensured_targets = self.config.get("ensured-targets", [])
-        skip_if_exists = self.config.get("skip-if-exists", [])
-
         if version == "editable":
-            build_kwargs = editable_build_kwargs or build_kwargs
+            build_kwargs = config.editable_build_kwargs or config.build_kwargs
 
         should_skip_build = False
-        if not build_function:
+        if not config.build_function:
             log.warning("No build function found")
             should_skip_build = True
 
-        elif skip_if_exists and version == "standard":
-            should_skip_build = should_skip(skip_if_exists)
+        elif config.skip_if_exists and version == "standard":
+            should_skip_build = should_skip(config.skip_if_exists)
             if should_skip_build:
                 log.info("Skip-if-exists file(s) found")
 
         # Get build function and call it with normalized parameter names.
-        if not should_skip_build:
-            build_func = get_build_func(build_function)
-            build_kwargs = normalize_kwargs(build_kwargs)
-            log.info(f"Building with {build_function}")
+        if not should_skip_build and config.build_function:
+            build_func = get_build_func(config.build_function)
+            build_kwargs = normalize_kwargs(config.build_kwargs)
+            log.info(f"Building with {config.build_function}")
             log.info(f"With kwargs: {build_kwargs}")
             build_func(self.target_name, version, **build_kwargs)
         else:
             log.info("Skipping build")
 
         # Ensure targets in distributable dists.
         if version == "standard":
-            ensure_targets(ensured_targets)
+            ensure_targets(config.ensured_targets)
 
         log.info("Finished running jupyter-builder")

hatch_jupyter_builder/utils.py

@@ -6,7 +6,7 @@
 import sys
 from pathlib import Path
 from shutil import which
-from typing import Any, Callable, Dict, List, Optional, Union
+from typing import Any, Callable, List, Mapping, Optional, Union
 
 if sys.platform == "win32":  # pragma: no cover
     from subprocess import list2cmdline
@@ -208,13 +208,15 @@ def normalize_cmd(cmd: Union[str, list]) -> List[str]:
     return cmd
 
 
-def normalize_kwargs(kwargs: Dict[str, str]) -> Dict[str, str]:
+def normalize_kwargs(kwargs: Mapping[str, str]) -> Mapping[str, str]:
     """Normalize the key names in a kwargs input dictionary"""
-    for key in list(kwargs):
+    result = {}
+    for key in kwargs:
         if "-" in key:
-            kwargs[key.replace("-", "_")] = kwargs[key]
-            del kwargs[key]
-    return kwargs
+            result[key.replace("-", "_")] = kwargs[key]
+        else:
+            result[key] = kwargs[key]
+    return result
 
 
 def run(cmd: Union[str, list], **kwargs: Any) -> int:

pyproject.toml

@@ -65,6 +65,7 @@ skip = ["check-links"]
 
 [tool.jupyter-releaser.options]
 ignore-glob = ["tests/data/**/README.md"]
+ignore-links = ["npm_builder_function"]
 
 [tool.tbump.version]
 current = "0.5.3"