Setup to generate documentation #14

Closed lorenzschmid closed 10 months ago

Hi @tgingold-cern

I was wondering about the current setup you are using to build the documentation? Looking at the doc/Makefile, you seem to use Asciidoctor (the Ruby version) as well as a script (a2x) from an older implementation of AsciiDoc (the Python version). I could not reproduce that setup but managed to generate a PDF using Asciidoctor PDF (based on the Ruby version). Although, the design of the PDF ended up being different (probably due to missing templates). Would you mind

[ ] elaborating on the setup you are using at CERN (including all dependencies),
[ ] preferably adding the setup to generate the PDF in an automated way (e.g. GitLab CI pipeline),
[ ] update the PDF currently included in the repository and since changed (e.g. with #11 or #12)

I am using the tools that are available with CentOS-7 (sure, that's old).

I will agree to switch to Asciidoctor PDF.

I will regenerate the doc.

CentOS-7 is what we are using too (and yes, it's old :D). Thanks for regenerating the documentation and letting us know about your exact setup.

Also, I have installed my own version of texlive (2019) to avoid errors with a2x.

That's good to know. We experimented with the following setup where (as far as I know) we could completely skip a2x but I'm unsure about any interaction with LaTeX.

gitlab-ci.yml extension:

documentation:
  stage: build
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes:
      - doc/**/*
  cache:
    - key:
        files:
          - doc/Gemfile.lock
      paths:
        - doc/vendor/bundle
  artifacts:
    paths:
      - doc/*.pdf
  script:
    - cd doc
    - bundle config set --local path 'vendor/bundle'
    - bundle install
    - make all

And the following Gemfile inside doc/:

source 'https://rubygems.org'
gem 'asciidoctor-pdf'

Looks ok to me. Can you create a PR so that I can easily test on my setup ? (I suppose you also have modified doc/Makefile)

See #15

tgingold-cern / cheby

Setup to generate documentation #14