Add index generation

.editorconfig

@@ -0,0 +1,8 @@
+root=true
+
+[*]
+indent_style=space
+indent_size=4
+insert_final_newline=true
+charset=utf8
+trim_trailing_whitespace=true

.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish JD
+on: ["pull_request", "push"]
+
+env:
+  DEST_DIR: _out
+  PYTHON_VERSION: 3.9
+
+jobs:
+  build:
+    # Only run on PRs if the source branch is on someone else's repo
+    if: "${{ github.event_name != 'pull_request' || github.repository != github.event.pull_request.head.repo.full_name }}"
+    runs-on: "ubuntu-20.04"
+    steps:
+      - name: "checkout repository"
+        uses: "actions/checkout@v2"
+      - name: "setup python ${{ env.PYTHON_VERSION }}"
+        uses: "actions/setup-python@v2"
+        with:
+          python-version: "${{ env.PYTHON_VERSION }}"
+      - name: "install dependencies"
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r _generator/requirements.txt
+      - name: "generate site"
+        run: |
+          python _generator/generate.py $DEST_DIR
+      - name: "publish"
+        if: "${{ github.event_name == 'push' && github.ref == 'refs/heads/data' }}"
+        uses: "JamesIves/[email protected]"
+        with:
+          branch: "gh-pages"
+          folder: "${{ env.DEST_DIR }}"
+          single-commit: true
+
+

.gitignore

@@ -0,0 +1,3 @@
+/_out/
+__pycache__/
+.vscode/

README.md

@@ -0,0 +1,7 @@
+# Sponge Javadocs
+
+This repository manages the publication of Javadoc for SpongeProjects.
+
+The current (`data`) branch holds a basic static generator and the raw javadoc data. Any new javadoc is published here.
+
+Github Actions runs the generator (in `_generator/`) on a push to this repository, which publishes the javadocs to the `gh-pages` branch, which is visible at https://jd.spongepowered.org.

_generator/.flake8

@@ -0,0 +1,2 @@
+[flake8]
+extend-ignore = E501

_generator/generate.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python
+
+import argparse
+from collections.abc import Sequence
+import jinja2
+import os
+from pathlib import Path
+from ruamel.yaml import YAML
+from semver import VersionInfo
+import shutil
+import sys
+from typing import NamedTuple
+
+
+class ModuleMetadata(NamedTuple):
+    name: str
+    versions: list[VersionInfo]
+    display_name: str = None
+    url: str = None
+
+
+def _generate_versions(jd_root: Path, metadata_file: Path) -> list[ModuleMetadata]: # module -> list[version]
+    """
+    Generate a mapping of project to module version.
+    """
+    loader = YAML()
+    data = loader.load(metadata_file)
+
+    result = []
+
+    for module in jd_root.iterdir():
+        dirname = module.name
+        if dirname.startswith(".") or dirname.startswith("_") or not module.is_dir():
+            continue
+
+        versions = [VersionInfo.parse(x.name) for x in module.iterdir() if x.is_dir and not x.name.startswith(".")]
+        versions.sort()
+
+        extra_metadata = data.get(dirname, {})
+        result.append(ModuleMetadata(
+            dirname,
+            versions,
+            extra_metadata.get("name", None),
+            extra_metadata.get("url", None)
+        ))
+
+    print(result)
+
+    return result
+
+
+def _create_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Generate static content for JD site")
+    parser.add_argument('dest', type=Path, help="Directory to generate to")
+    parser.add_argument('--jd-root', type=Path, help="Directory to search for module Javadoc in", default='.')
+    parser.add_argument('--metadata', type=Path, help="YAML file containing extra component metadata", default="components.yaml")
+
+    script_dir = Path(__file__).parent
+
+    parser.add_argument("--template-root", type=Path, help="Directory to read templates from", default = script_dir / 'tmpl')
+    parser.add_argument("--static-root", type=Path, help="Static root, for files copied directly", default = script_dir / 'static')
+    return parser
+
+
+def _do_generate(dest: Path, jd_root: Path, metadata_file: Path, template_root: Path, static_root: Path):
+    print(f"Generating from jd={jd_root}, metadata_file={metadata_file}, tmpl={template_root}, static={static_root} -> {dest}")
+
+    # Setup, generate metadata
+    module_versions = _generate_versions(jd_root, metadata_file)
+    if dest.exists():
+        shutil.rmtree(dest)
+    dest.mkdir(exist_ok=True)
+
+    # Generate templates
+    tmpl_env = jinja2.Environment(
+        loader=jinja2.FileSystemLoader(template_root),
+        undefined=jinja2.StrictUndefined,
+        autoescape=True,
+        keep_trailing_newline=True
+    )
+    tmpl_env.globals["module_versions"] = module_versions
+
+    for tmpl in template_root.glob('**/*'):
+        tmpl_out = dest / tmpl.relative_to(template_root)
+        print(f"Writing {tmpl} to {tmpl_out}")
+        template = tmpl_env.get_template(str(tmpl.relative_to(template_root)))
+        with tmpl_out.open(mode = 'wt') as fp:
+            fp.write(template.render())
+
+    # Copy static content
+    for static in static_root.glob('**/*'):
+        static_out = dest / static.relative_to(static_root)
+        print(f"Writing {static} to {static_out}")
+        shutil.copy2(static, static_out)
+
+    # link JD directories into the output dir
+    for module in module_versions:
+        module_out = dest / module.name
+        print(f"Copying {module.name} to {module_out}")
+        shutil.copytree(jd_root / module.name, module_out, copy_function=os.link,symlinks=True)
+        print(f"Generating 'latest' symlink for {module.name}")
+        (module_out / 'latest/').symlink_to(Path(str(max(module.versions))))
+
+        # SpongeAPI legacy path support (it's ugly but it works)
+        if module.name == "spongeapi":
+            newest_legacy = VersionInfo(7, 3, 0)
+            for version in module.versions:
+                if version <= newest_legacy:
+                    (dest / str(version)).symlink_to(module.name + '/' + str(version))
+
+    print(f"Generated successfully to {dest}")
+
+
+def main(args: Sequence[str]):
+    parser = _create_parser()
+    parsed = parser.parse_args(args)
+    _do_generate(parsed.dest, parsed.jd_root, parsed.metadata, parsed.template_root, parsed.static_root)
+
+
+if __name__ == "__main__":
+    main(sys.argv[1:])

_generator/requirements.txt

@@ -0,0 +1,3 @@
+Jinja2>=3.0.0,<4.0.0
+semver>=2.13.0,<3.0.0
+ruamel.yaml>=0.17

_generator/static/404.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"/>
+  <title>Not Found | Sponge Javadocs</title>
+  <link rel="stylesheet" type="text/css" href="/style.css">
+</head>
+<body>
+  <div class="title">Not Found | Sponge Javadocs</div>
+  <div id="listContainer">
+    <div style="text-align: center; padding: 20px;">
+      <div class="header" style="padding-bottom: 20px;">The page you are looking for could not be found.</div>
+      <a href="/">Go to the index</a>
+    </div>
+  </div>
+</body>
+</html>

_generator/static/CNAME

@@ -0,0 +1 @@
+jd.spongepowered.org

_generator/static/style.css

@@ -0,0 +1,42 @@
+body {
+  margin: 0;
+  background-color: #2b2b2b;
+  color: white;
+  /* this list is copypasted straight from bootstrap kek */
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
+  font-size: 24px;
+}
+
+.title {
+  margin: 0;
+  background-color: #383838;
+  text-align: center;
+  padding: 15px;
+}
+
+.header {
+  font-weight: bold;
+  text-align: center;
+  width: 100%;
+  padding-top: 20px;
+}
+
+#listContainer {
+  display: flex;
+  justify-content: center;
+  flex-wrap: wrap;
+  margin: 15px;
+
+}
+
+#listContainer > div {
+  width: 300px;
+  background-color: #383838;
+  border-radius: 5px;
+  margin: 20px 10px;
+}
+
+a {
+  color: #99b8ff;
+}
+

_generator/tmpl/index.html

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8"/>
+    <title>Sponge Javadocs</title>
+    <link rel="stylesheet" type="text/css" href="style.css">
+</head>
+<body>
+<div class="title">Sponge Javadocs</div>
+<div id="listContainer">
+    {% for module in module_versions %}
+    <div>
+        {% set module_title = module.display_name if module.display_name else module.name %}
+        {% if module.url %}
+        <div class="header"><a href="{{ module.url }}">{{ module_title }}</a></div>
+        {% else %}
+        <div class="header">{{ module_title }}</div>
+        {% endif %}
+        <ul>
+            {% for version in module.versions | reverse %}
+            <li><a href="/{{ module.name }}/{{ version }}/">{{ version }}</a></li>
+            {% endfor %}
+        </ul>
+    </div>
+    {% endfor %}
+</div>
+</body>
+</html>

components.yaml

@@ -0,0 +1,13 @@
+# Extra component metadata
+# Format:
+#
+#    directoryname:
+#        name: User-readable Name
+#        url: A URL to link to in the module info
+#        group: Module group for display -- empty string to display at top level
+#        snapshot-regex: (optional): regex to use to determine if a version should be considered a snapshot. Default `-SNAPSHOT$`
+
+spongeapi:
+    name: SpongeAPI
+    url: https://github.com/SpongePowered/SpongeAPI
+    group: ""