update to readme and doc build

README.md

@@ -17,14 +17,30 @@ This package includes a variety of [maze generation algorithms](maze_dataset/gen
 |---|---|---|---|
 | ![Maze generated via percolation](docs/assets/maze_perc.png) |  ![Maze generated via constrained randomized depth first search](docs/assets/maze_dfs_constrained.png)  |  ![Maze with random heatmap](docs/assets/mazeplot_heatmap.png)  |  ![MazePlot with solution](docs/assets/mazeplot_path.png)  |
 
+# Installation
+This package is [available on PyPI](https://pypi.org/project/maze-dataset/), and can be installed via
+```
+pip install maze-dataset
+```
 
-# Usage
+# Docs
+
+The full hosted documentation is available at [https://understanding-search.github.io/maze-dataset/](https://understanding-search.github.io/maze-dataset/).
 
-Most of the functionality is demonstrated in the ipython notebooks in the `notebooks/` folder.
+Additionally:
 
-- [`demo_dataset.ipynb`](notebooks/demo_dataset.ipynb) how to easily create a dataset of mazes, utilities for filtering the generates mazes via properties, and basic visualization. View this one first.
-- [`demo_tokenization.ipynb`](notebooks/demo_tokenization.ipynb) converting mazes to and from textual representations, as well as utilities for working with them.
-- [`demo_latticemaze.ipynb`](notebooks/demo_latticemaze.ipynb) internals of the `LatticeMaze` and `SolvedMaze` objects, and advanced visualization.
+- our notebooks serve as a good starting point for understanding the package:
+    - the [notebooks](https://understanding-search.github.io/maze-dataset/notebooks) page in the docs has links to the rendered notebooks
+    - the [`notebooks`](https://github.com/understanding-search/maze-dataset/tree/main/notebooks) folder has the source notebooks
+- combined, single page docs are available as:
+    - [plain text](https://understanding-search.github.io/maze-dataset/combined/maze_dataset.txt)
+    - [html](https://understanding-search.github.io/maze-dataset/combined/maze_dataset.html)
+    - [github markdown](https://github.com/understanding-search/maze-dataset/tree/main/docs/combined/maze_dataset.md)
+    - [pandoc markdown](https://github.com/understanding-search/maze-dataset/tree/main/docs/combined/maze_dataset.md)
+- test coverage reports are available on the [coverage](https://understanding-search.github.io/maze-dataset/coverage) page or the [`coverage/`](https://github.com/understanding-search/maze-dataset/tree/main/docs/coverage) folder
+- generation benchmark results are available on the [benchmarks](https://understanding-search.github.io/maze-dataset/benchmarks) page or the [`benchmarks/`](https://github.com/understanding-search/maze-dataset/tree/main/docs/benchmarks) folder
+
+# Usage
 
 ## Creating a dataset
 
@@ -42,19 +58,10 @@ cfg: MazeDatasetConfig = MazeDatasetConfig(
 )
 ```
 
-and then pass this config to the `MazeDataset.from_config` factory method:
+and then pass this config to the `MazeDataset.from_config` method:
 
 ```python
-dataset: MazeDataset = MazeDataset.from_config(
-    # your config
-	cfg,
-    # and all this below is completely optional
-	# do_download=False,
-	# load_local=False,
-	# do_generate=True,
-    # save_local=True,
-	# gen_parallel=False,
-)
+dataset: MazeDataset = MazeDataset.from_config(cfg)
 ```
 
 This method can search for whether a dataset with matching config hash already exists on your filesystem in the expected location, and load it if so. It can also generate a dataset on the fly if needed.
@@ -87,14 +94,6 @@ MazePlot(maze).plot()
 ![textual and visual output formats](docs/output_formats.png)
 
 
-
-# Installation
-This package is [available on PyPI](https://pypi.org/project/maze-dataset/), and can be installed via
-```
-pip install maze-dataset
-```
-
-
 # Development
 
 This project uses [Poetry](https://python-poetry.org/docs/#installation) for development. To install with dev requirements, run

docs/make_docs.py

@@ -125,13 +125,20 @@ def ignore_warnings(config_path: str | Path = Path("pyproject.toml")):
         </a>.
     <ul>
         {% for notebook in notebooks %}
-        <li><a href="{{ notebook.html }}">{{ notebook.ipynb }}</a></li>
+        <li><a href="{{ notebook.html }}">{{ notebook.ipynb }}</a> {{ notebook.desc }}</li>
         {% endfor %}
     </ul>
     <a href="../">Back to index</a>
 """
 
 
+NOTEBOOK_DESCRIPTIONS: dict[str, str] = dict(
+    demo_dataset="how to easily create a dataset of mazes, utilities for filtering the generates mazes via properties, and basic visualization. View this one first.",
+    demo_tokenization="converting mazes to and from textual representations, as well as utilities for working with them.",
+    demo_latticemaze="internals of the `LatticeMaze` and `SolvedMaze` objects, and advanced visualization.",
+)
+
+
 def convert_notebooks(
     source_path: Path|str = Path("notebooks"),
     output_path: Path|str = Path("docs/notebooks"),
@@ -147,6 +154,7 @@ def convert_notebooks(
         dict(
             ipynb=notebook.name,
             html=notebook.with_suffix(".html").name,
+            desc=NOTEBOOK_DESCRIPTIONS.get(notebook.stem, ""),
         )
         for notebook in notebook_names
     ]

docs/resources/theme.css

@@ -6,8 +6,8 @@
 .pdoc {
     --text: #212529;
     --muted: #6c757d;
-    --link: #3660a5;
-    --link-hover: #1659c5;
+    --link: #0a64f4;
+    --link-hover: #265cb2;
     --code: #f8f8f8;
     --active: #fff598;
 

makefile

@@ -108,9 +108,6 @@ docs-notebooks:
 	@echo "generate html docs for notebooks"
 	$(PYTHON) docs/make_docs.py --notebooks
 
-# $(PANDOC) -f markdown -t pdf $(DOCS_DIR)/combined/$(PACKAGE_NAME).md -o $(DOCS_DIR)/combined/$(PACKAGE_NAME).pdf
-
-
 .PHONY: cov
 cov:
 	@echo "generate coverage reports (run tests manually)"
@@ -126,7 +123,7 @@ benchmark:
 	$(PYTHON) docs/benchmarks/benchmark_generation.py
 
 .PHONY: docs
-docs: docs-html docs-combined cov
+docs: docs-html docs-combined docs-notebooks cov
 	@echo "generate all documentation"
 
 .PHONY: clean-docs