riscv / docs-spec-template Goto Github PK

per this: https://asciidoctor.org/docs/asciidoc-recommended-practices/#document-extension
We can exclude .asciidoc and .asc files from the repo with a simple check https://pre-commit.com/index.html#fail

PR to follow...

This is follow up to this post: https://lists.riscv.org/g/sig-documentation/message/126

I'd be happy to submit a PR for a pre-commit solution

Warnings like the following occurred on during the build-pdf and create-release workflows:

Node.js 12 actions are deprecated. For more information see: https://github.blog/changelog/2022-09-22-github-actions-all-actions-will-begin-running-on-node16-instead-of-node12/. ...

I don't know if there needs to be a discussion on the settings but I'll describe here my thoughts.

My PR would have the folllowing settings:

  - repo: https://github.com/jumanjihouse/pre-commit-hook-yamlfmt
    rev: 0.2.3
    hooks:
      - id: yamlfmt
        args: [--mapping, '2', --sequence, '4', --offset, '2']

Based on:

• defaults of yamlfmt IMO add too much whitespace
• these settings are a close match to what currently exists
• 2 spaces, in general is enough to denote indentation w/o extending lines into the the > MAX_LINE_LENGTH
• this formatting passes yamllint (if that was to be deployed)

PR to follow...

Similar to other specs:

• https://github.com/riscv-non-isa/riscv-sbi-doc
• https://github.com/riscv/riscv-isa-manual

I think it makes sense to organize the content in the spec in a separate dir, rather than at the top level where it can be harder to find with other content.

I will provide a PR...

This could be as simple as using asciidoctor tool and/or a static site generator like jekyll or antora could be use to provide a more feature rich website.

possible features:

• deploy to github pages
• search
• complex nav (ability to have multi-page, intra-page)
• links
  • edit source
  • file issue

At least one spec, has multiple output docs. Rather than adding them individually to the existing Makefile structure, it could be refactored to easily support this.

PR to follow will do following:

• add variable at top to allow for multiple src docs
• parallelize builds (both pdf/html and mulitiple docs)
• remove duplication

Specification states: https://wiki.riscv.org/display/HOME/Specification+States

Currently this: https://github.com/riscv/docs-spec-template/blob/main/.github/workflows/build-pdf.yml#L16

Prompted by this: riscv/riscv-zabha@ea4f0a1

❯ git submodule status
 005cb0db1c46c31fff163914f3e480dbda0306be docs-resources (remotes/origin/HEAD)

Tried with docker:

❯ make
Checking if Docker is available...
Docker is available, building inside Docker container...
make[1]: Entering directory '/home/kbroch/rvi/riscv/docs-spec-template'
Starting build inside Docker container...
make build-docs
make[2]: Entering directory '/home/kbroch/rvi/riscv/docs-spec-template'
docker run --rm -v /home/kbroch/rvi/doc-team-repos/docs-spec-template:/build -w /build riscvintl/riscv-docs-base-container-image:latest /bin/sh -c " asciidoctor-pdf --trace -a compress -a mathematical-format=svg -a revnumber=v0.0.0 -a revremark=Draft -a revdate=2024-04-25 -a pdf-fontsdir=docs-resources/fonts -a pdf-theme=docs-resources/themes/riscv-pdf.yml  -D build --failure-level=ERROR --require=asciidoctor-bibtex --require=asciidoctor-diagram --require=asciidoctor-mathematical src/spec-sample.adoc "
asciidoctor: ERROR: could not locate or load the built-in pdf theme `docs-resources/themes/riscv-pdf.yml' because of NoMethodError undefined method `each' for "646b74":String; reverting to default theme
make[2]: *** [Makefile:61: spec-sample.pdf] Error 1
make[2]: Leaving directory '/home/kbroch/rvi/riscv/docs-spec-template'
make[1]: *** [Makefile:78: build-container] Error 2
make[1]: Leaving directory '/home/kbroch/rvi/riscv/docs-spec-template'
make: *** [Makefile:68: build] Error 2

and without:

❯ make build-no-container 
Starting build...
make SKIP_DOCKER=true build-docs
make[1]: Entering directory '/home/kbroch/rvi/riscv/docs-spec-template'
asciidoctor-pdf --trace -a compress -a mathematical-format=svg -a revnumber=v0.0.0 -a revremark=Draft -a revdate=2024-04-25 -a pdf-fontsdir=docs-resources/fonts -a pdf-theme=docs-resources/themes/riscv-pdf.yml  -D build --failure-level=ERROR --require=asciidoctor-bibtex --require=asciidoctor-diagram --require=asciidoctor-mathematical src/spec-sample.adoc 
asciidoctor: ERROR: could not locate or load the built-in pdf theme `docs-resources/themes/riscv-pdf.yml' because of NoMethodError undefined method `each' for "646b74":String; reverting to default theme

            val.each do |key2, val2|
               ^^^^^
make[1]: *** [Makefile:61: spec-sample.pdf] Error 1
make[1]: Leaving directory '/home/kbroch/rvi/riscv/docs-spec-template'
make: *** [Makefile:83: build-no-container] Error 2

The following problems with building asciidoctor PDFs has been seen in the build-pdf workflow.

To identify the error, look for the following error details inside the "bundle install" twistie:

linking shared-object mathematical/mathematical.so
/usr/bin/ld: cannot find -lwebp: No such file or directory
collect2: error: ld returned 1 exit status
make: *** [Makefile:262: mathematical.so] Error 1

It's most commonly seen (at this time) on local forks where "ubuntu-latest" is now running 22.04, instead of 20.04.

The bug is being investigated but the final fix is not yet available due to intricacies of building the gem mathematical file.

The simplest work around at this time is to hard-code the version statement in your .github/workflows/build-pdf.yml file from:

runs-on: ubuntu-latest

to:

runs-on: ubuntu-20.04

This statement should be found on or around line 22 of the file.

I think it would be good if the riscv adoc documents were as small as the latex ones.
Especially considering the fact that I often approach github repos/releases that download at less than 500kbps.

Currently the adoc unpriv is 8x the size of the latex one.

There is a simple -a compress command to put in a makefile, which in my case, yielded 314KiB document out of 1.2MiB. Didn't visibly affect build time.

There are also some external tools that claim to strip more.

related ref's:

• riscv-admin/docs-sig#25
• riscv/riscv-docs-base-container-image#6

Specific error information from Ubuntu 22.04 build:

linking shared-object mathematical/mathematical.so
/usr/bin/ld: cannot find -lzstd: No such file or directory
collect2: error: ld returned 1 exit status
make: *** [Makefile:262: mathematical.so] Error 1

make failed, exit code 2