📝 refactor docs generation

* 📝 switch to a Markdown extension that displays better on GitHub

* 📝 deduplicate source of README.md/index.md

* 📝 simplify and unnest nav generation

#40

README.md

@@ -407,6 +407,8 @@ Alternatively, you can install it with [pip]:
 pip install hatch hatch-pip-compile
 ```
 
+<!--skip-->
+
 ---
 
 ---
@@ -417,6 +419,8 @@ pip install hatch hatch-pip-compile
 
 #### See the [Changelog]
 
+<!--skip-->
+
 [pip-compile]: https://github.com/jazzband/pip-tools
 [pip-sync]: https://github.com/jazzband/pip-tools
 [hatch]: https://github.com/pypa/hatch

docs/contributing.md

@@ -2,25 +2,25 @@
 
 ## Environment Setup
 
-!!! tip "pipx"
-
-    This documentaion uses [pipx] to
-    install and manage non-project command line tools like `hatch` and
-    `pre-commit`. If you don't already have `pipx` installed, make sure to
-    see their [documentation](https://pypa.github.io/pipx/installation/).
-    If you prefer not to use `pipx`, you can use `pip` instead.
+> TIP: **pipx**
+> 
+> This documentaion uses [pipx] to
+> install and manage non-project command line tools like `hatch` and
+> `pre-commit`. If you don't already have `pipx` installed, make sure to
+> see their [documentation](https://pypa.github.io/pipx/installation/).
+> If you prefer not to use `pipx`, you can use `pip` instead.
 
 1.  Install [hatch](https://github.com/pypa/hatch)
 
     ```shell
     pipx install hatch
     ```
 
-    !!! note "pre-commit"
-
-        Hatch will attempt to set up pre-commit hooks for you using
-        [pre-commit]. If you don't already,
-        make sure to install pre-commit as well: `pipx install pre-commit`
+    > NOTE: **pre-commit**
+    >
+    > Hatch will attempt to set up pre-commit hooks for you using
+    > [pre-commit]. If you don't already,
+    > make sure to install pre-commit as well: `pipx install pre-commit`
 
 2.  Build the Virtual Environment
 

docs/gen_ref_pages.py → docs/gen_pages.py

@@ -11,7 +11,6 @@
 
 project_dir = Path(__file__).resolve().parent.parent
 source_code = project_dir.joinpath("hatch_pip_compile")
-nav = mkdocs_gen_files.Nav()
 
 for path in sorted(source_code.rglob("*.py")):
     module_path = path.relative_to(project_dir).with_suffix("")
@@ -26,13 +25,15 @@
     elif parts[-1] == "__main__":
         continue
 
-    nav[parts] = doc_path.as_posix()
-
     with mkdocs_gen_files.open(full_doc_path, "w") as fd:
-        ident = ".".join(parts)
-        fd.write(f"::: {ident}")
+        fd.write(f"# `{parts[-1]}`\n\n::: {'.'.join(parts)}")
 
     mkdocs_gen_files.set_edit_path(full_doc_path, path)
 
-with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
-    nav_file.writelines(nav.build_literate_nav())
+
+with open("README.md") as in_file:
+    readme_content = in_file.read()
+# Exclude parts that are between two exact `<!--skip-->` lines
+readme_content = "\n".join(readme_content.split("\n<!--skip-->\n")[::2])
+with mkdocs_gen_files.open("index.md", "w") as index_file:
+    index_file.write(readme_content)