Convert the project to docs-template

[jjscheel]

The Config documentation need to be in the RISC-V format. I've discussed getting there with @timsifive and he agreed to let me take a look at this.

Four things were needed:

1. Import of docs-template project into a subdirectory (docs-template)
2. Addition of symbolic links in the resources/ and resources/images/ directories for the fonts/ themes/ and images/ (RISC-V)
3. Updates to the Makefile to use more options on asciidoctor build
4. Updates to the main .adoc file to include more variables for the build

I got it working and inadvertently pushed my updates back to main in commit #19430d9. Sorry about that!!!

If anyone sees problems with the updates, feel free to reach out or add information to this issue. I'll leave it open until we've had a chance to discuss it more and prove things are working as expected.

Again, my apologies for the push to master! -Jeff

[jjscheel]

FYI, per item 1 above, the import was done using Git Submodules. Note that this essentially "links" to that repo at a commit value. Over time, we will want to update this. More information on Git Submodules can be found here.

As a result of this change, the next update people make locally will require two additional commands (once). They are:

git submodule init
git submodule update

If one does not do this after updating, the build will fail with an error like:

$ make
asciidoctor-pdf -v \
-r asciidoctor-diagram \
-a toc \
-a compress \
-a pdf-style=resources/riscv-themes/riscv-pdf.yml \
-a pdf-fontsdir=resources/riscv-fonts \
-o riscv-configuration-structure-draft.pdf riscv-configuration-structure-draft.adoc
asciidoctor: ERROR: could not locate or load the built-in pdf theme `resources/riscv-themes/riscv-pdf.yml'; reverting to default theme
No such file or directory - notoserif-regular-subset.ttf not found in resources/riscv-fonts
Use --trace for backtrace
make: *** [Makefile:13: riscv-configuration-structure-draft.pdf] Error 1 

[timsifive]

I've reverted your change because I couldn't easily get the new stuff to build on my machine. I got some horrendous error regarding asciidoctor-diagram (after I installed it).

[jjscheel]

Sure. I will gladly create a PR. However, it would be helpful to know the error details as it sounds like an installation/setup issue. Can you post an error log?

[timsifive]

I also just rushed through #69, so can you either rebase your branch or merge it into yours. Then whenever you update the PR github will try to build the PDF. If it works, then the problem is on my end. If not, you'll probably have to edit the action to install the appropriate stuff.

[timsifive]

The error I got was:

tnewsome@compy-linux:~/SiFive/configuration-structure$ make
asciidoctor-pdf -v \
-r asciidoctor-diagram \
-a toc \
-a compress \
-a pdf-style=resources/riscv-themes/riscv-pdf.yml \
-a pdf-fontsdir=resources/riscv-fonts \
-o riscv-configuration-structure-draft.pdf riscv-configuration-structure-draft.adoc
Traceback (most recent call last):
    6: from /usr/bin/asciidoctor-pdf:25:in `<main>'
    5: from /usr/lib/ruby/vendor_ruby/asciidoctor/cli/options.rb:274:in `parse!'
    4: from /usr/lib/ruby/vendor_ruby/asciidoctor/cli/options.rb:274:in `each'
    3: from /usr/lib/ruby/vendor_ruby/asciidoctor/cli/options.rb:276:in `block in parse!'
    2: from /usr/lib/ruby/vendor_ruby/polyglot.rb:65:in `require'
    1: from /usr/lib/ruby/2.7.0/rubygems/core_ext/kernel_require.rb:92:in `require'
/usr/lib/ruby/2.7.0/rubygems/core_ext/kernel_require.rb:92:in `require': cannot load such file -- asciidoctor-diagram (LoadError)
    20: from /usr/bin/asciidoctor-pdf:25:in `<main>'
    19: from /usr/lib/ruby/vendor_ruby/asciidoctor/cli/options.rb:274:in `parse!'
    18: from /usr/lib/ruby/vendor_ruby/asciidoctor/cli/options.rb:274:in `each'
    17: from /usr/lib/ruby/vendor_ruby/asciidoctor/cli/options.rb:276:in `block in parse!'
    16: from /usr/lib/ruby/vendor_ruby/polyglot.rb:65:in `require'
    15: from /usr/lib/ruby/2.7.0/rubygems/core_ext/kernel_require.rb:156:in `require'
    14: from /usr/lib/ruby/2.7.0/rubygems/core_ext/kernel_require.rb:168:in `rescue in require'
    13: from /usr/lib/ruby/2.7.0/rubygems/core_ext/kernel_require.rb:168:in `require'
    12: from /var/lib/gems/2.7.0/gems/asciidoctor-diagram-2.2.1/lib/asciidoctor-diagram.rb:1:in `<top (required)>'
    11: from /var/lib/gems/2.7.0/gems/asciidoctor-diagram-2.2.1/lib/asciidoctor-diagram.rb:1:in `require_relative'
    10: from /var/lib/gems/2.7.0/gems/asciidoctor-diagram-2.2.1/lib/asciidoctor-diagram/a2s.rb:2:in `<top (required)>'
     9: from /var/lib/gems/2.7.0/gems/asciidoctor-diagram-2.2.1/lib/asciidoctor-diagram/a2s.rb:2:in `require_relative'
     8: from /var/lib/gems/2.7.0/gems/asciidoctor-diagram-2.2.1/lib/asciidoctor-diagram/a2s/extension.rb:1:in `<top (required)>'
     7: from /var/lib/gems/2.7.0/gems/asciidoctor-diagram-2.2.1/lib/asciidoctor-diagram/a2s/extension.rb:1:in `require_relative'
     6: from /var/lib/gems/2.7.0/gems/asciidoctor-diagram-2.2.1/lib/asciidoctor-diagram/a2s/converter.rb:2:in `<top (required)>'
     5: from /var/lib/gems/2.7.0/gems/asciidoctor-diagram-2.2.1/lib/asciidoctor-diagram/a2s/converter.rb:2:in `require_relative'
     4: from /var/lib/gems/2.7.0/gems/asciidoctor-diagram-2.2.1/lib/asciidoctor-diagram/util/cli_generator.rb:2:in `<top (required)>'
     3: from /usr/lib/ruby/vendor_ruby/polyglot.rb:65:in `require'
     2: from /usr/lib/ruby/2.7.0/rubygems/core_ext/kernel_require.rb:92:in `require'
     1: from /usr/lib/ruby/2.7.0/rubygems/core_ext/kernel_require.rb:92:in `require'
/usr/lib/ruby/2.7.0/tempfile.rb:121:in `<top (required)>': superclass mismatch for class Tempfile (TypeError)
make: *** [Makefile:13: riscv-configuration-structure-draft.pdf] Error 1

[jjscheel]

Did you install asciidoctor-diagram independently or did you follow the directions in the Install Doc?

[timsifive]

I installed it independently. I didn't realize there was an install doc. But it doesn't mention Linux in any case. Although it does hint that maybe I need a completely separate asciidoctor toolchain.

Anyway, when you get the automated check to pass on #70 then I'll be able to do whatever that does.

[jjscheel]

Updates in the latest PR include:

1. Removal of the comment in the Makefile.
2. Return to including the version in the title.

Let me know if there's anything else needed.

[jjscheel]

Thanks, @timsifive, for you patience and support!!! I'll leave this open for now.

Please feel free to close when you feel we are beyond any "side effects" of the migration.