Add GitHub pages build (#27)

This change adds support for builing a GitHub pages static site reproducing the content of the GitHub markdown as well as built versions of the LaTeX specification. This change is a starting point, there is still a lot of work to improve the visual look and functionality of the site as well as the LaTeX to HTML generation.

A preview of the site is available off my fork of the repository here:
https://llvm-beanz.github.io/hlsl-specs

Note: Some links that are hard-coded in the markdown files will not work until the page is generated and deployed to GitHub Pages.

* Change how raw regions are marked

This fixes rendering issues in 0002 and 0005. It also puts the raw
marker into an HTML comment so that it doesn't display in GitHub's
markdown preview. I've added the raw markings to the template too so
future proposals will inherit it for the full proposal.

I suspect using liquid markup in proposals will be rare if ever.

.github/workflows/jekyll-gh-pages.yml

@@ -0,0 +1,62 @@
+# Sample workflow for building and deploying a Jekyll site to GitHub Pages
+name: Deploy Jekyll with GitHub Pages dependencies preinstalled
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Setup Pages
+        uses: actions/configure-pages@v2
+      - name: Install dependencies
+        run: |
+          sudo apt -y install texlive
+          sudo apt -y install texlive-latex-extra
+          sudo apt -y install pandoc
+      - name: Build LaTeX
+        run: |
+          cmake -B build ${{github.workspace}}/specs/language
+          cmake --build build --target html
+          cmake --build build --target pdf
+          cp build/hlsl.pdf ${{github.workspace}}/specs/
+          cp build/html/* ${{github.workspace}}/specs/
+      - name: Build with Jekyll
+        uses: actions/jekyll-build-pages@v1
+        with:
+          source: ./
+          destination: ./_site
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

README.md

@@ -1,7 +1,17 @@
+<img src="https://microsoft.github.io/hlsl-specs/resources/HLSL.png" width="128">
+
 # HLSL Specifications
 
 This repository contains documentation for HLSL feature proposals and specifications. Please see the documentation for
 the HLSL Feature [Proposal Process](docs/Process.md) for more information on proposals.
+
+A listing of the active proposals is available [here](proposals/).
+
+This repository also contains specifications for the HLSL language. The draft
+HLSL specification is available in
+[HTML](https://microsoft.github.io/hlsl-specs/specs/hlsl.html) and
+[PDF](https://microsoft.github.io/hlsl-specs/specs/hlsl.pdf).
+
 ## Contributing
 
 This project welcomes contributions and suggestions.  Most contributions require you to agree to a

proposals/0002-cxx-attributes.md

@@ -1,3 +1,4 @@
+<!-- {% raw %} -->
 # C++ Attributes
 
 * Proposal: [0002](0002-cxx-attributes.md)
@@ -32,8 +33,7 @@ parameter declarations using a `:` to separate the name from the specifier:
 SamplerState samp1 : register(s5);
 Texture2D<float4> text1 : register(t3);
 
-float4 main(float2 a : A) : SV_Target
-{
+float4 main(float2 a : A) : SV_Target {
   ...
 }
 ```
@@ -65,8 +65,8 @@ code is ambiguous and currently _not_ interpreted as a bitfield declaration:
 If we wish to add source annotations to more grammatical elements in the future
 we will encounter more ambiguities because the `:` character has other meanings
 in C and modern C++ as well. to name a few examples: the ternary operator
-(`<boolean> ? <a> : <b>`), range-based for syntax (`for (<var> :
-<collection>)`), and switch label marking (`case 1:`).
+(`condition ? a : b`), range-based for syntax (`for (variable : collection)`),
+and switch label marking (`case 1:`).
 
 We will also encounter ambiguities with the `[]` syntax. We may encounter issues
 with array indexing which valid in contexts where we may wish to annotate
@@ -119,6 +119,9 @@ Below are a few more examples of C++ attributes that we could support:
     float f = [[hlsl::strict]](1.0 * 2.0); // applies to the parenthesis expression `(...)`.
 
     [[hlsl::unroll]] // applies to the for-loop expression.
-    for (int x = 0; x < 10; ++x) {}
+    for (int x = 0; x < 10; ++x) {
+      ...
+    }
   }
 ```
+<!-- {% endraw %} -->

proposals/0005-strict-initializer-lists.md

@@ -1,3 +1,5 @@
+<!-- {% raw %} -->
+
 # Strict Initializer Lists
 
 * Proposal: [0005](0005-strict-initializer-lists.md)
@@ -71,3 +73,5 @@ not be backwards compatible to older HLSL versions.
 
 This syntax conflicts with the effects annotation syntax which DXC supports
 parsing but is unsupported in code generation. Should we just stop parsing it?
+
+<!-- {% endraw %} -->

proposals/index.md

@@ -0,0 +1,8 @@
+# Current Active Proposals
+
+{% assign doclist = site.pages | sort: 'url'  %}
+{% for doc in doclist %}
+{% if doc.name contains '.md' and doc.dir == '/proposals/' and doc.name != 'index.md' %}
+* [{{ doc.name }}]({{ doc.url | relative_url }})
+{% endif %}
+{% endfor %}

proposals/templates/basic-template.md

@@ -1,3 +1,5 @@
+<!-- {% raw %} -->
+
 # Feature name
 
 ## Instructions
@@ -72,3 +74,5 @@ reviewing.
 
 Take a moment to acknowledge the contributions of people other than the author
 and sponsor.
+
+<!-- {% endraw %} -->

specs/language/CMakeLists.txt

@@ -12,14 +12,18 @@ if (NOT MAKEGLOSSARIES_COMPILER)
   message(FATAL_ERROR "Could not find makeglossaries")
 endif()
 
+if (NOT PANDOC_COMPILER)
+  find_program(PANDOC_COMPILER pandoc)
+endif()
+
 set(intermediate_dir ${CMAKE_BINARY_DIR}/tmp/)
 
 message(STATUS "Generating targets for: ${PROJECT_NAME}")
 set(main_file ${CMAKE_CURRENT_SOURCE_DIR}/${PROJECT_NAME}.tex)
 set(out_dir ${CMAKE_BINARY_DIR})
 
 add_custom_target(${PROJECT_NAME}-dirs
-                  COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_BINARY_DIR}
+                  COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_BINARY_DIR}/html
                   COMMENT "Creating directories for ${PROJECT_NAME}")
 
 add_custom_target(${PROJECT_NAME}-prebuild
@@ -43,3 +47,8 @@ add_custom_target(pdf
                   WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
                   DEPENDS ${main_file} ${PROJECT_NAME}-prebuild ${PROJECT_NAME}-glossaries)
 
+add_custom_target(html
+                  COMMAND ${PANDOC_COMPILER} ${main_file} -f latex -t html -s -o ${CMAKE_BINARY_DIR}/html/hlsl.html
+                  COMMENT "Generating HTML"
+                  WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+                  DEPENDS ${main_file} ${PROJECT_NAME}-prebuild ${PROJECT_NAME}-glossaries ${PROJECT_NAME}-dirs)