Page MenuHomeLubuntu Development
Create Task
Maniphest T109

Manual as PDF
Open, NormalPublic
Actions

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

rMANUAL Lubuntu Manual
D102rMANUALf7084ae1e48d Jenkins Pipeline for Manual

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.
Leok added a subscriber: Leok.May 29 2020, 10:21 AM
apt-ghetto added a revision: D102: Jenkins Pipeline for Manual.Oct 18 2020, 12:42 PM
tsimonq2 added a commit: rMANUALf7084ae1e48d: Jenkins Pipeline for Manual.Oct 28 2020, 6:47 AM
tsimonq2 added a subscriber: tsimonq2.Oct 28 2020, 6:57 AM
$ 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
tsimonq2 added a subscriber: teward.Oct 28 2020, 6:57 AM

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

apt-ghetto added a comment.Oct 28 2020, 9:41 AM

Docker in LXC

teward added a comment.Dec 30 2020, 7:22 PM

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

teward added a comment.Dec 30 2020, 8:01 PM

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.

teward added a comment.Dec 30 2020, 8:01 PM

However, you still get brokenness:

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

So something in the workflow is broken ;)

kc2bez added a subscriber: kc2bez.Dec 30 2020, 8:16 PM
teward added a comment.Dec 30 2020, 8:49 PM

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

teward closed this task as Resolved.Dec 30 2020, 8:49 PM
kc2bez reopened this task as Open.Dec 30 2020, 9:39 PM

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.

kc2bez updated the task description. (Show Details)Dec 30 2020, 9:43 PM
apt-ghetto added a comment.Dec 31 2020, 5:13 PM

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.

wxl added a subscriber: wxl.Dec 31 2020, 6:36 PM

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 :)