Flatten documentation under /public directory (#76)

README.md

@@ -36,16 +36,8 @@ You can install the query generator using [pip](https://pip.pypa.io/en/stable/in
 pip install pqg
 ```
 
-Alternatively, you can use the local web playground:
-
-```bash
-cd www && bun install && bunx --bun vite
-```
-
-_n.b._ This command will require you to have [bun](https://bun.sh/) installed on your machine.
-
-This will spin up a development server at `http://localhost:5173` where you can interact with the playground.
-You can upload your schemas, tweak query parameters and generate queries.
+Alternatively, you can check out the hosted [web playground](https://dislmcgill.github.io/pandas-query-generator/)
+if you're interested in generating queries fast with little setup.
 
 ## Usage
 
@@ -164,12 +156,12 @@ print(*query_pool, sep='\n\n')
 
 Comprehensive internal documentation is generated using the
 [sphinx](https://www.sphinx-doc.org/en/master/index.html#) Python package, and a
-live instance is hosted at
-[https://dislmcgill.github.io/pandas-query-generator/docs/index.html](https://dislmcgill.github.io/pandas-query-generator/docs/index.html).
+[live instance](https://dislmcgill.github.io/pandas-query-generator/docs/index.html)
+is hosted alongside the web playground.
 
 ## How does it work?
 
-Check out the [paper](https://github.com/DISLMcGill/pandas-query-generator/blob/master/docs/paper.pdf) in the `/docs` folder for more information!
+Check out the [paper](https://github.com/DISLMcGill/pandas-query-generator/blob/master/docs/paper.pdf) in the docs folder for more information!
 
 ## Prior Art
 

bin/convert-docs.py

@@ -0,0 +1,112 @@
+import argparse
+import glob
+import os
+import shutil
+from pathlib import Path
+
+from bs4 import BeautifulSoup
+
+
+def create_flat_filename(original_path):
+  parts = Path(original_path).parts
+
+  if parts[0] in {'html', '_modules', '_static', '_sources'}:
+    parts = parts[1:]
+
+  return '_'.join(parts)
+
+
+def copy_to_flat_directory(source_dir, target_dir):
+  path_mapping = {}
+
+  os.makedirs(target_dir, exist_ok=True)
+
+  for root, _, files in os.walk(source_dir):
+    for file in files:
+      source_path = os.path.join(root, file)
+      relative_path = os.path.relpath(source_path, source_dir)
+      new_filename = create_flat_filename(relative_path)
+      target_path = os.path.join(target_dir, new_filename)
+
+      if os.path.exists(target_path):
+        base, ext = os.path.splitext(new_filename)
+        counter = 1
+        while os.path.exists(target_path):
+          new_filename = f'{base}_{counter}{ext}'
+          target_path = os.path.join(target_dir, new_filename)
+          counter += 1
+
+      shutil.copy2(source_path, target_path)
+      path_mapping[relative_path] = new_filename
+
+  return path_mapping
+
+
+def update_html_references(file_path, path_mapping):
+  with open(file_path, 'r', encoding='utf-8') as f:
+    soup = BeautifulSoup(f, 'html.parser')
+
+  for link in soup.find_all(['a', 'link', 'script', 'img']):
+    if link.has_attr('href'):
+      href = link['href']
+
+      for _, _ in path_mapping.items():
+        if href.startswith('_'):
+          old_parts = href.split('/')
+          if len(old_parts) > 1:
+            new_href = create_flat_filename(href)
+            link['href'] = new_href
+        elif href in path_mapping:
+          link['href'] = path_mapping[href]
+
+    if link.has_attr('src'):
+      src = link['src']
+
+      for _, _ in path_mapping.items():
+        if src.startswith('_'):
+          old_parts = src.split('/')
+          if len(old_parts) > 1:
+            new_src = create_flat_filename(src)
+            link['src'] = new_src
+        elif src in path_mapping:
+          link['src'] = path_mapping[src]
+
+  with open(file_path, 'w', encoding='utf-8') as f:
+    f.write(str(soup))
+
+
+def parse_args():
+  parser = argparse.ArgumentParser(
+    description='Flatten a Sphinx documentation directory structure and update HTML references.'
+  )
+
+  parser.add_argument(
+    '-s', '--source', required=True, help='Source directory containing Sphinx documentation'
+  )
+
+  parser.add_argument(
+    '-o', '--output', required=True, help='Output directory for flattened documentation'
+  )
+
+  return parser.parse_args()
+
+
+def main():
+  args = parse_args()
+
+  print(f'Copying files from {args.source} to flat directory {args.output}...')
+
+  path_mapping = copy_to_flat_directory(args.source, args.output)
+
+  print('Updating references in HTML files...')
+  html_files = glob.glob(os.path.join(args.output, '*.html'))
+
+  for html_file in html_files:
+    print(f'Processing {html_file}...')
+    update_html_references(html_file, path_mapping)
+
+  print(f"\nDone! Flattened documentation is in '{args.output}' directory.")
+
+
+if __name__ == '__main__':
+  main()

docs/source/conf.py → docs/config/conf.py

@@ -6,8 +6,14 @@
 project = 'pqg'
 copyright = '2024, Liam Scalzulli'
 author = 'Liam Scalzulli'
+
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.viewcode']
 templates_path = ['_templates']
 exclude_patterns = []
-html_theme = 'alabaster'
+
+html_absolute_paths = True
 html_static_path = ['_static']
+html_theme = 'alabaster'
+html_use_index = True
+html_use_modindex = True
+html_use_permalink = True

justfile

@@ -15,21 +15,7 @@ all: fmt check readme
 build:
   uv build
 
-demo:
-  just run \
-    --groupby-aggregation-probability 0.5 \
-    --max-groupby-columns 5 \
-    --max-merges 10 \
-    --max-projection-columns 10 \
-    --max-selection-conditions 10 \
-    --num-queries 1000 \
-    --projection-probability 0.5 \
-    --schema examples/tpch/schema.json \
-    --selection-probability 0.5 \
-    --sort \
-    --verbose
-
-deploy:
+deploy-web: generate-docs
   cd www && bun run build && bunx gh-pages -d dist
 
 dev-deps:
@@ -44,8 +30,14 @@ count:
 fmt:
   ruff check --select I --fix && ruff format
 
+fmt-web:
+  cd www && prettier --write .
+
 generate-docs:
-  cd docs && just build
+  cd docs && uv run sphinx-build -M html config build
+  rm -rf www/public/docs
+  uv run ./bin/convert-docs.py --source docs/build/html --output www/public/docs
+  just fmt-web
 
 generate-example-output:
   ./bin/generate-example-output