initialize docs

Author: Tsche

.devcontainer/Dockerfile

@@ -0,0 +1,24 @@
+FROM antora/antora
+
+
+RUN apk add --no-cache \
+bash \
+curl \
+git \
+ruby \
+ruby-dev \
+build-base \
+libxml2-dev \
+libxslt-dev
+
+RUN gem install --no-document rouge nokogiri
+
+RUN apk add --no-cache python3 py3-pip
+
+RUN pip install pyyaml
+RUN pip install watchdog
+
+RUN npm i antora @antora/lunr-extension
+
+USER node
+

.devcontainer/devcontainer.json

@@ -0,0 +1,11 @@
+{
+  "name": "Antora",
+  "build": {
+    "context": "..",
+    "dockerfile": "Dockerfile"
+  },
+  "mounts": [
+		// workaround for google repo
+    "source=${localWorkspaceFolder}/../.repo/projects/docs.git,target=/workspaces/docs/.git,type=bind,consistency=cached"
+  ]
+}

.github/workflows/docs.yaml

@@ -0,0 +1,46 @@
+name: Build and publish docs
+
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+concurrency:
+  group: github-pages
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    container:
+      build:
+        context: .
+        dockerfile: .devcontainer/Dockerfile
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Generate Site
+        run: python tools/docs.py build
+
+      - name: Upload Artifacts
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: build
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -16,3 +16,7 @@ _site/
 # counterproductive to check this file into the repository.
 # Details at https://github.com/github/pages-gem/issues/768
 Gemfile.lock
+
+**/build/
+
+node_modules/

antora-playbook.yml

@@ -0,0 +1,25 @@
+asciidoc:
+  attributes:
+    source-highlighter: rouge
+    rouge-style: github
+site:
+  title: fuquery
+  start_page: _::index.adoc
+output:
+  dir: build
+content:
+  sources:
+  - url: .
+    start_paths: [.]
+  # - url: ..
+  #   branches: HEAD
+  #   start_paths: [projects/test/docs]
+  # - url: ..
+  #   branches: HEAD
+  #   start_paths: [projects/util/docs]
+ui:
+  bundle:
+    url: ui
+antora:
+  extensions:
+  - '@antora/lunr-extension'

antora.yml

@@ -0,0 +1,5 @@
+name: _
+version: ~
+title: fuquery
+nav:
+- modules/ROOT/nav.adoc

modules/ROOT/attachments/fuquery.mp3

@@ -0,0 +1,10 @@
+* xref:projects.adoc[]
+
+* xref:contributing.adoc[]
+** xref:contributing/setup.adoc[]
+** xref:contributing/cpp_style.adoc[]
+** xref:contributing/documentation.adoc[]
+
+* Maintainer Information
+** xref:maintaining/new_project.adoc[]
+** xref:maintaining/docker.adoc[]

modules/ROOT/nav.adoc

@@ -0,0 +1,50 @@
+= Contributing
+
+Thank you for your interest in contributing to fuquery projects. Contributions of all sizes and shapes are welcome - not just code contributions.
+
+This document applies to all repositories in the https://github.com/fuquery[fuquery organization] unless a repository specifies otherwise.
+
+== Before You Start
+
+- Please check existing issues and pull requests to avoid duplicate work
+- For larger changes, consider opening an issue or reaching out on https://discord.gg/YWfdM2tctt[Discord] first to discuss the approach
+- Try to keep contributions narrow in scope
+
+== Reporting Issues
+
+When reporting a problem, please include:
+
+- A clear description of the issue
+- Steps to reproduce
+- Expected vs. actual behavior
+- Relevant environment information if applicable
+
+If possible, include a minimal reproducer.
+
+== Submitting Changes
+
+1. Fork the repository and create a topic branch
+2. Make your changes
+3. Submit a pull request
+
+Pull requests should:
+
+- Clearly describe the change and motivation
+- Stay focused on a single topic
+- Include updates to documentation when relevant
+- Include tests for the introduced changes
+
+Maintainers may request revisions before merging.
+
+== Style
+
+The style used in C++ fuquery projects is roughly documented in xref:contributing/cpp_style.adoc[].
+
+== Licensing
+
+By submitting a contribution, you agree that it will be licensed under the same license as the target project.  
+fuquery projects are typically licensed under **MIT** or **0BSD**.
+
+== AI-Generated Contributions
+
+Contributions generated wholly or partially by AI systems are generally not welcome.

modules/ROOT/pages/contributing.adoc

@@ -0,0 +1,70 @@
+= C++ Code Style
+
+This document briefly summarizes stylistic choices made in fuquery subprojects.
+
+== Layout and namespaces
+Currently there are three top-level namespaces used in fuqery projects:
+
+* `rsl` for the rsl project
+* `re` for the retest project
+* `erl` for **e**xperimental **r**eflective **l**ibraries
+
+Relative to the repository's root the primary include path must be `include/<namespace>` where `<namespace>` is the associated top-level namespace. Files in this folder are considered part of the public API, may contribute to the associated top-level namespace directly and shall not have a file extension.
+
+Implementation details shall be collected in a directory whose name starts with `_impl`. For top-level namespaces shared between projects, the project name must be included (ie `include/rsl/_impl_config` for rsl-config). Implementation detail headers shall have the file extension `.hpp` and may **not** contribute to the associated top-level namespace directly.
+
+== Macros
+=== Dollar macros
+[source,c++ diff]
+----
+- RSL_INLINE(always)
++ $inline(always)
+void foo() {}
+----
+
+MSVC, GCC and Clang explicitly support `$` in identifiers. However, GCC notes that this might cause issues with some target assemblers. Since macros are gone at that point, the use of dollars in macro identifiers is unproblematic.
+
+This distinguishes macros clearly from other source constructs, therefore use of dollar macro identifiers is encouraged.
+
+== Identifiers
+=== Format
+Two different styles are used throughout the projects. For top-level namespaces standard library style should be used, meaning:
+[source,c++]
+----
+// namespaces are always snake_case
+namespace rsl {
+
+// snake_case for types in the rsl namespace
+struct some_type;
+
+// snake_case for functions, variables etc
+void some_func();
+constexpr inline bool some_var = true;
+}
+----
+
+However, in implementation details we are free to use a slightly different style:
+[source,c++]
+----
+// implementation detail namespaces begin with _impl_
+namespace rsl::_impl_foo {
+
+// PascalCase for types
+struct SomeType;
+
+// snake_case for functions, variables etc
+void some_func();
+constexpr inline bool some_var = true;
+}
+----
+
+=== Uglifying members
+To ensure specific types are structural types, we sometimes cannot have non-public data members. Whenever this is the case, uglify the identifiers by prepending `_impl_`.
+
+[source,c++ diff]
+----
+struct something_structural {
+-  int secret;
++  int _impl_secret;
+};
+----