Page MenuHomeLubuntu Development

Manual as PDF
Open, NormalPublic

Description

Our manual is in a Git repository. This can be used to generate both the website and a PDF.

This should be a master task to collect ideas and give an overview. For the different steps and final ideas, subtasks should be created with the detailed descriptions and actions.

A rough workflow:

  1. A Jenkins job is started automatically every night/week/month/release or triggered by a member e.g. @lynorian
  2. The Jenkins job starts a minimal Linux with the required tools installed as a building environment
  3. The latest commits are pulled into the building environment
  4. A PDF is built directly from source by branch/version in the building environment
  5. If the PDF is built successfully, deploy the PDF on the website, so that users can download it for offline use.

Todo:

  • Setting up a Jenkins job (or systemd or ...)
  • Check the PDF output and tweak it (CSS?)
  • Set up deployment
  • Define the interval of the creation

Revisions and Commits

Event Timeline

apt-ghetto triaged this task as Normal priority.Aug 13 2019, 4:58 PM
apt-ghetto created this task.
apt-ghetto added a project: Documentation Team.
$ docker build -t 8e412831f28fd62a57d2b81c5f3292b9354b7b81 -f Dockerfile .
Sending build context to Docker daemon  115.4MB
Step 1/2 : FROM ubuntu:focal
focal: Pulling from library/ubuntu
6a5697faee43: Pull complete 
ba13d3bc422b: Pull complete 
a254829d9e55: Pull complete 
Digest: sha256:fff16eea1a8ae92867721d90c59a75652ea66d29c05294e6e2f898704bdb8cf1
Status: Downloaded newer image for ubuntu:focal
 ---> d70eaf7277ea
Step 2/2 : RUN export DEBIAN_FRONTEND=noninteractive &&     apt-get update && apt-get install --yes --no-install-recommends     python3-pip     python3-sphinx     latexmk     texlive     texlive-formats-extra     arcanist     build-essential     python3-sphinx-rtd-theme     python3-sphinx-bootstrap-theme
 ---> Running in a59b504f9a82
OCI runtime create failed: container_linux.go:349: starting container process caused "process_linux.go:449: container init caused \"rootfs_linux.go:58: mounting \\\"proc\\\" to rootfs \\\"/var/lib/docker/vfs/dir/7497de1b8053cc4c8931cf844dea638b3789f29354e9d63a0157e5cf0ef33437\\\" at \\\"/proc\\\" caused \\\"permission denied\\\"\"": unknown

I have a feeling the Jenkins host is running in LXD. @teward?

Yes, Jenkins is running inside an LXD environment. I can try and set up nested dockerization in that.

PDF builds should work now. At least, Docker can execute. The container Jenkins is in did not have nesting enabled. We're no longer getting instant failures.

However, you still get brokenness:

java.lang.NoSuchMethodError: No such DSL method 'publishHTML' found among steps

So something in the workflow is broken ;)

Fixed. Needed another plugin added (HTML Publisher). Working now.

Thanks @teward for your assistance with CI. We may have some further sysadmin things dealing with this task once we figure out what we want to do with this.
I want to go on the record and say this is fantastic @apt-ghetto! Very nice work.
One minor thing, in the task you mentioned looking at the output and tweaking the CSS. I think we need to poke at the TOC if possible. I am not sure what our options are there but it gets all bunched up and the sub-chapters are not visible in the Table.
We still have some TODO's left, I will edit the task so those items are check boxes indicating where we stand with the task.

Thanks for setting up Jenkins.

As far as I understand the Sphinx docu, CSS is used only for HTML.

The PDF is based on LaTeX (see the docu). Anyone with some time and maybe also some LaTeX and/or Sphinx skills, can try to improve it.
It would also help, if someone is checking every page of the PDF export (for example page 6 shows what can go wrong).

After a first glance, the TOC can be modified on line 248.

In the next weeks, I will not have much time.

I used to take notes in my discrete math classes in LaTeX, so if help is needed there, I can probably assist. However, I suspect that @lynorian's Sphinx skills will likely suffice.

My first question: why the blank pages?

Finally: @apt-ghetto GREAT idea and excellent work and much thanks as always to @teward for getting the infrastructure to behave :)