feat: basic page on modern compiled projects

.pre-commit-config.yaml

@@ -81,3 +81,9 @@ repos:
         language: pygrep
         entry: PyBind|Numpy|Cmake|CCache|Github|PyTest
         exclude: (.pre-commit-config.yaml|docs/pages/guides/style\.md)$
+      - id: cog
+        name: Cog the pages
+        language: python
+        entry: cog -P -r -I ./helpers
+        files: "^docs/pages/guides/packaging_compiled.md"
+        additional_dependencies: [cogapp, cookiecutter]

Gemfile.lock

@@ -88,11 +88,10 @@ GEM
     sass-embedded (1.63.6)
       google-protobuf (~> 3.23)
       rake (>= 13.0.0)
-    sass-embedded (1.63.6-x86_64-darwin)
-      google-protobuf (~> 3.23)
     terminal-table (3.0.2)
       unicode-display_width (>= 1.1.1, < 3)
     unicode-display_width (2.4.2)
+    wdm (0.1.1)
     webrick (1.8.1)
 
 PLATFORMS
@@ -106,7 +105,9 @@ DEPENDENCIES
   just-the-docs (~> 0.5.3)
   kramdown-parser-gfm
   rubocop (~> 1.52)
+  tzinfo (>= 1, < 3)
   tzinfo-data
+  wdm (~> 0.1.1)
 
 BUNDLED WITH
    2.3.7

copier.yml

@@ -66,4 +66,4 @@ _subdirectory: "{% raw %}{{cookiecutter.project_name}}{% endraw %}"
 
 _jinja_extensions:
   - copier_templates_extensions.TemplateExtensionLoader
-  - extensions.py:CookiecutterNamespace
+  - helpers/extensions.py:CookiecutterNamespace

docs/_includes/pyproject.md

@@ -0,0 +1,87 @@
+## pyproject.toml: project table
+
+The metadata is specified in a [standards-based][metadata] format:
+
+```toml
+[project]
+name = "package"
+description = "A great package."
+readme = "README.md"
+authors = [
+  { name = "My Name", email = "[email protected]" },
+]
+maintainers = [
+  { name = "My Organization", email = "[email protected]" },
+]
+requires-python = ">=3.8"
+
+dependencies = [
+  "typing_extensions",
+]
+
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "License :: OSI Approved :: BSD License",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Physics",
+]
+
+[project.urls]
+Homepage = "https://github.com/organization/package"
+Documentation = "https://package.readthedocs.io/"
+"Bug Tracker" = "https://github.com/organization/package/issues"
+Discussions = "https://github.com/organization/package/discussions"
+Changelog = "https://package.readthedocs.io/en/latest/changelog.html"
+```
+
+You can read more about each field, and all allowed fields, in
+[packaging.python.org][metadata],
+[Flit](https://flit.readthedocs.io/en/latest/pyproject_toml.html#new-style-metadata)
+or [Whey](https://whey.readthedocs.io/en/latest/configuration.html). Note that
+"Homepage" is special, and replaces the old url setting.
+
+### Extras
+
+It is recommended to use extras instead of or in addition to making requirement
+files. These extras a) correctly interact with install requires and other
+built-in tools, b) are available directly when installing via PyPI, and c) are
+allowed in `requirements.txt`, `install_requires`, `pyproject.toml`, and most
+other places requirements are passed.
+
+Here is an example of a simple extras:
+
+```toml
+[project.optional-dependencies]
+test = [
+  "pytest >=6.0",
+]
+mpl = [
+  "matplotlib >=2.0",
+]
+```
+
+Self dependencies can be used by using the name of the package, such as
+`dev = ["package[test,examples]"]`, but this requires Pip 21.2 or newer. We
+recommend providing at least `test` and `docs`.
+
+### Command line
+
+If you want to ship an "app" that a user can run from the command line, you need
+to add a `script` entry point. The form is:
+
+```toml
+[project.scripts]
+cliapp = "packakge.__main__:main"
+```
+
+The format is command line app name as the key, and the value is the path to the
+function, followed by a colon, then the function to call. If you use
+`__main__.py` as the file, then `python -m` followed by the module will also
+work to call the app (`__name__` will be `"__main__"` in that case).
+
+[metadata]: https://packaging.python.org/en/latest/specifications/core-metadata/

docs/pages/guides/gha_basic.md

@@ -2,7 +2,7 @@
 layout: page
 title: "GHA: GitHub Actions intro"
 permalink: /guides/gha-basic/
-nav_order: 11
+nav_order: 10
 parent: Topical Guides
 custom_title: GitHub Actions introduction
 ---

docs/pages/guides/gha_pure.md

@@ -2,7 +2,7 @@
 layout: page
 title: "GHA: Pure Python wheels"
 permalink: /guides/gha-pure/
-nav_order: 12
+nav_order: 11
 parent: Topical Guides
 custom_title: GitHub Actions for pure Python wheels
 ---

docs/pages/guides/gha_wheels.md

@@ -2,7 +2,7 @@
 layout: page
 title: "GHA: Binary wheels"
 permalink: /guides/gha-wheels/
-nav_order: 13
+nav_order: 12
 parent: Topical Guides
 custom_title: GitHub Actions for Binary Wheels
 ---

docs/pages/guides/mypy.md

@@ -2,7 +2,7 @@
 layout: page
 title: "Static type checking"
 permalink: /guides/mypy/
-nav_order: 8
+nav_order: 9
 parent: Topical Guides
 ---
 

docs/pages/guides/packaging_classic.md

@@ -2,7 +2,7 @@
 layout: page
 title: Classic packaging
 permalink: /guides/packaging_classic/
-nav_order: 6
+nav_order: 7
 parent: Topical Guides
 ---