riscv/riscv-isa-manual

Publish nightly draft to RISC-V's Github Pages

VitalyAnkh opened this issue · 2 comments

VitalyAnkh commented

The draft HTML version of the RISC-V ISA manual is available for download on the release pages but is not currently hosted on a webpage. Could it be published on RISC-V's GitHub Pages, similar to how riscv-cheri is hosted at riscv.github.io/riscv-cheri/, to facilitate easier browsing of the latest draft?

It appears this was previously discussed in this issue: #175, but it has not yet been implemented as a published webpage.

wmat commented
Timmmm commented

The problem is you can't link to an HTML file on Github releases, and opening it is a bit awkward (download and then open, then you end up with a lot of ... (1).html files.

We did this for CHERI: https://riscv.github.io/riscv-cheri/

It's quite easy to set up (see here):


      # Upload GitHub pages artefacts.
      - name: Make gitlab pages directory
        run: mkdir dist && cp build/*.html dist/index.html
        if: github.event_name == 'push'

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: dist
        if: github.event_name == 'workflow_dispatch' || github.event_name == 'push'

...

  # Deploy HTML to Github pages.
  deploy:
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'

    needs: build

    permissions:
      pages: write
      id-token: write

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

The big downside is it just deploys the latest version as the Github Pages page, so the URL just always points to the latest version and you can't see old versions.

@wmat what's the timeline for this documentation library? If it's going to be a year maybe it is worth using Github Pages in the interim.

Also will you be able to link directly into the specs in the documentation library e.g. https://specs.riscv.org/riscv-isa-manual/privileged/v1.015/index.html#some_section, and will it have all the same draft releases as this repo?