Start adding more docs

docs/source/background/index.rst

@@ -2,8 +2,15 @@ Background
 ==========
 Explanation. Clarification and discussion of key topics.
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Contents:
+Hatch Jupyter Builder is a plugin for the `hatchling` Python build backend.
+It is primarily targeted for package authors who are providing JavaScript
+as part of their Python packages.
 
-Coming soon!
+Typical use cases are Jupyter Lab Extensions and Jupyter Widgets.
+
+The ``hatchling`` build backend is part of the ``hatch`` 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
+and runtime files.

docs/source/how_to_guides/index.rst

@@ -6,4 +6,5 @@ Step-by-step guides. Covers key tasks and operations and common problems
    :maxdepth: 1
    :caption: Contents:
 
-Coming soon!
+   migrating_javascript_projects
+   migrating_data_files_projects

docs/source/how_to_guides/migrating_data_files_projects.md

@@ -0,0 +1,54 @@
+# Migrating Python Projects that used JavaScript
+
+For existing projects that used `setuptools` and optionally the
+`get_data_files()` function from `jupyter_packaging`, we offer a migration
+script that will convert your project to use `hatchling`.
+These projects can include Jupyter Kernels or Jupyter Server Extensions
+that ship with `data_files`.
+
+Create a new branch for your migration and run the following:
+
+```bash
+pip install hatch_jupyter_builder
+python -m hatch_jupyter_builder.migrate .
+```
+
+The migration script will do its best to convert metadata
+from `setup.py` and `setup.cfg` into appropriate modernized
+`pyproject.toml` metadata. Much of the migration is done by
+`hatch` itself, including the mapping of `data-files` configuration
+to [`shared-data`](https://hatch.pypa.io/latest/plugins/builder/wheel/#options).
+
+If there are things that are found that cannot be automatically
+migrated, a warning will print at the end of the migration script.
+Typically this will be a notice to put the actual version string
+in your `_version.py` file.
+
+The migration assumes that you will be using [`tbump`](https://github.com/your-tools/tbump) to manage versions.
+`tbump` is a project that is used by many of the core Jupyter projects
+to maintain version for a project. For example, if you have a `_version.py`
+and a `package.json` file that are meant to share a version, `tbump`
+can handle keeping them in sync.
+
+If some other custom logic that was in your `setup.py`, you may need
+to include a `hatch_build.py` file, similar to the one used by [`ipykernel`](https://github.com/ipython/ipykernel/blob/main/hatch_build.py). You will need to add a [custom metadata hook](https://hatch.pypa.io/latest/plugins/metadata-hook/custom/#custom-metadata-hook) as well.
+
+As an additional assurance, you can compare the files produced by the
+migrated configuration to those you previously produced.
+
+To do this, clone your repository to another folder, and run the following:
+
+```bash
+python -m hatch_jupyter_builder.compare_migrated . <clean-checkout-path> wheel
+```
+
+This will build the wheel in both directories and compare their contents.
+You can repeat the process with the `sdist` option as well.
+
+For some other examples of migrated packages, see
+
+- [ipyparallel](https://github.com/ipython/ipyparallel/blob/main/pyproject.toml) (includes a `hatch_build.py` file with a custom script to provide a Lab and Notebook extension)
+
+- [jupyter-server-terminals](https://github.com/jupyter-server/jupyter_server_terminals/blob/main/pyproject.toml) - a Jupyter Server extension
+
+- [jupyter_client](https://github.com/jupyter/jupyter_client/blob/main/pyproject.toml) (regular python package with no `shared-data`)

docs/source/how_to_guides/migrating_javascript_projects.md

@@ -0,0 +1,52 @@
+# Migrating Python Projects that used JavaScript
+
+For existing projects that shipped with JavaScript, which includes
+Jupyter Lab Extensions, Jupyter Widgets, and Jupyter Notebook Extensions,
+we provide a script to help automate the process.
+
+Create a new branch for your migration and run the following:
+
+```bash
+pip install hatch_jupyter_builder
+python -m hatch_jupyter_builder.migrate .
+```
+
+The migration script will do its best to convert metadata
+from `setup.py` and `setup.cfg` into appropriate modernized
+`pyproject.toml` metadata. Much of the migration is done by
+`hatch` itself, including the mapping of `data-files` configuration
+to [`shared-data`](https://hatch.pypa.io/latest/plugins/builder/wheel/#options).
+
+If the package was using `jupyter_packaging`, we also provide
+appropriate `hatch_jupyter_builder` config.
+
+If there are things that are found that cannot be automatically
+migrated, a warning will print at the end of the migration script.
+Typically this will be a notice to put the actual version string
+in your `_version.py` file.
+
+The migration assumes that you will be using [`tbump`](https://github.com/your-tools/tbump) to manage versions.
+`tbump` is a project that is used by many of the core Jupyter projects
+to maintain version for a project. For example, if you have a `_version.py`
+and a `package.json` file that are meant to share a version, `tbump`
+can handle keeping them in sync.
+
+The configuration and behavior of the `npm_builder` helper function is
+similar to the one provided by `jupyter_packaging`.
+
+As an additional assurance, you can compare the files produced by the
+migrated configuration to those you previously produced.
+
+To do this, clone your repository to another folder, and run the following:
+
+```bash
+python -m hatch_jupyter_builder.compare_migrated . <clean-checkout-path> wheel
+```
+
+This will build the wheel in both directories and compare their contents.
+You can repeat the process with the `sdist` option as well.
+
+For some examples of migrated packages that provide JavaScript, see:
+
+- [notebook](https://github.com/jupyter/notebook/blob/main/pyproject.toml) (JupyterLab and Server Extensions)
+- [jupyter_server](https://github.com/jupyter-server/jupyter_server/blob/main/pyproject.toml) (build step to include CSS for default pages).