Issues building the docs

[suy]

While trying to check locally the #102 PR, I tried to build the docs locally following the instructions, but had some issues.

First:

$ ninja lexy_docs
[0/2] Re-checking globbed directories...
[3/5] Generating assets/cpp/playground_headers.single.hpp
FAILED: docs/assets/cpp/playground_headers.single.hpp /home/alex/projects/3rdparty/lexy/build/docs/assets/cpp/playground_headers.single.hpp 
cd /home/alex/projects/3rdparty/lexy/docs && /home/alex/projects/3rdparty/lexy/docs/../support/resolve-lexy-headers.py assets/cpp/playground_headers.hpp assets/cpp/playground_headers.single.hpp
  File "/home/alex/projects/3rdparty/lexy/docs/../support/resolve-lexy-headers.py", line 43
    print(f'usage: {sys.argv[0]} <input> <output>')
                                                 ^
SyntaxError: invalid syntax
[4/5] Generating content/learn/changelog.adoc
ninja: build stopped: subcommand failed.

I just fixed by hand editing the python script, as the first python on my path is still Python 2. Just changing the shebang temporarily to python3 does the trick. But then I got this one, which is just beyond what I can easily understand:

$ ninja lexy_docs
[0/2] Re-checking globbed directories...
[5/5] cd /home/alex/projects/3rdparty/lexy/docs && /usr/bin/hugo --minify
FAILED: docs/CMakeFiles/lexy_docs /home/alex/projects/3rdparty/lexy/build/docs/CMakeFiles/lexy_docs 
cd /home/alex/projects/3rdparty/lexy/docs && /usr/bin/hugo --minify
Building sites … ERROR 2022/12/11 12:35:40 [en] REF_NOT_FOUND: Ref "/reference/dsl/": "/home/alex/projects/3rdparty/lexy/docs/content/reference/dsl/effect.adoc:20:15": page not found
ERROR 2022/12/11 12:35:40 [en] REF_NOT_FOUND: Ref "/reference/dsl/": "/home/alex/projects/3rdparty/lexy/docs/content/reference/dsl/flags.adoc:65:14": page not found
ERROR 2022/12/11 12:35:41 [en] REF_NOT_FOUND: Ref "/reference/dsl/": "/home/alex/projects/3rdparty/lexy/docs/content/reference/dsl/subgrammar.adoc:52:19": page not found
ERROR 2022/12/11 12:35:41 [en] REF_NOT_FOUND: Ref "/reference/dsl/": "/home/alex/projects/3rdparty/lexy/docs/content/reference/action/parse_as_tree.adoc:50:106": page not found
ERROR 2022/12/11 12:35:41 [en] REF_NOT_FOUND: Ref "/reference/dsl/": "/home/alex/projects/3rdparty/lexy/docs/content/reference/grammar.adoc:50:29": page not found
ERROR 2022/12/11 12:35:41 [en] REF_NOT_FOUND: Ref "/reference/dsl/": "/home/alex/projects/3rdparty/lexy/docs/content/reference/grammar.adoc:167:25": page not found
ERROR 2022/12/11 12:35:42 [en] REF_NOT_FOUND: Ref "/reference/dsl/": "/home/alex/projects/3rdparty/lexy/docs/content/reference/_index.adoc:95:94": page not found
Total in 3557 ms
Error: Error building site: logged 7 error(s)
ninja: build stopped: subcommand failed.

I don't understand this tricks for generating the website. :-) I know AsciiDoctor well (and I'm glad that you use it!), but I think this is just related to Hugo or the custom build.

Thank you very much for Lexy. <3

[foonathan]

Just fixed by hand editing the python script, as the first python on my path is still Python 2. Just changing the shebang temporarily to python3 does the trick.

Yeah, I'm using Arch where python means python3. ;)

I don't understand this tricks for generating the website. :-) I know AsciiDoctor well (and I'm glad that you use it!), but I think this is just related to Hugo or the custom build.

That's odd. What version of hugo are you using? For reference, this is how CI does it:

lexy/.github/workflows/website.yml

Lines 14 to 31 in 9449964

	steps:
	- uses: actions/checkout@v2
	- name: Install asciidoctor
	run: sudo gem install asciidoctor pygments.rb
	- name: Install hugo
	uses: peaceiris/actions-hugo@v2
	with:
	hugo-version: 'latest'
	extended: true
	- name: Create Build Environment
	run: cmake -E make_directory build
	- name: Configure
	working-directory: build/
	run: cmake $GITHUB_WORKSPACE -DLEXY_BUILD_DOCS=ON -DLEXY_BUILD_EXAMPLES=OFF -DLEXY_BUILD_TESTS=OFF
	- name: Build docs
	working-directory: build/
	run: cmake --build . --target lexy_docs

[suy]

I was using the hugo package from the (not-so-new) linux distro. After getting the latest version from Github releases, I get a different error now (I was building with ninja lexy_docs before, but using cmake --build like in the snippet from the CI yields the same):

[0/2] Re-checking globbed directories...
[5/5] cd /home/alex/projects/3rdparty/lexy/docs && /home/alex/local/bin/hugo --minify
FAILED: docs/CMakeFiles/lexy_docs /home/alex/projects/3rdparty/lexy/build/docs/CMakeFiles/lexy_docs 
cd /home/alex/projects/3rdparty/lexy/docs && /home/alex/local/bin/hugo --minify
Start building sites … 
hugo v0.108.0-a0d64a46e36dd2f503bfd5ba1a5807b900df231d+extended linux/amd64 BuildDate=2022-12-06T13:37:56Z VendorInfo=gohugoio
ERROR 2022/12/13 17:36:58 benchmark_json.adoc: /usr/lib/ruby/2.7.0/rubygems.rb:275:in `find_spec_for_exe': can't find gem asciidoctor (>= 0.a) with executable asciidoctor (Gem::GemNotFoundException)
ERROR 2022/12/13 17:36:58 benchmark_json.adoc: from /usr/lib/ruby/2.7.0/rubygems.rb:294:in `activate_bin_path'
ERROR 2022/12/13 17:36:58 benchmark_json.adoc: from /home/alex/local/gems/bin/asciidoctor:23:in `<main>'
ERROR 2022/12/13 17:36:58 asciidoctor rendering benchmark_json.adoc: failed to execute binary "asciidoctor" with args [-a source-highlighter=pygments --no-header-footer -]: /usr/lib/ruby/2.7.0/rubygems.rb:275:in `find_spec_for_exe': can't find gem asciidoctor (>= 0.a) with executable asciidoctor (Gem::GemNotFoundException)
        from /usr/lib/ruby/2.7.0/rubygems.rb:294:in `activate_bin_path'
        from /home/alex/local/gems/bin/asciidoctor:23:in `<main>'

The last lines are repeated many times. Invoking asciidoctor by itself on any adoc file works fine. I just have set GEM_HOME to ~/local/gems to have all this extra packages in a separate directory without root access. I'm not sure if Hugo does some sanitizing to the environment, or if it's a way of invoking the asciidoctor program detecting it from system Ruby that doesn't work.

Anyway, it's probably not too important, as maybe it's an upstream issue in Hugo or Ruby, and my setup maybe it's not so common, so feel free to close the issue. :)

Thank you!

[foonathan]

Anyway, it's probably not too important, as maybe it's an upstream issue in Hugo or Ruby, and my setup maybe it's not so common, so feel free to close the issue. :)

Ok :D