Should a Guix package include documentation dependencies to be considered complete?

Should a Guix package include documentation dependencies to be considered complete?

[jgart]

Hi Guixers,

For example,

https://github.com/Abjad/abjad/blob/63520b2a00ef59f3302837f843d069c3946baa6c/docs/Makefile#L113

We have abjad packaged but we don't necessarily have all the dependencies needed to build everything that abjad provides such as a PDF document that it mentions in its project Makefile.

Should we include the LaTeX dependencies in the abjad package?

Should all Python packages include the required dependencies to build documentation?

We currently include all the dependencies to run the tests, why not do
the same for documentation building?

Should we make it a requirement or goal to always package a given package's "documentation-inputs"?

There's another thread where I already talked on this topic with roptat
briefly. I'll find it and link it soon.

Re: Should a Guix package include documentation dependencies to be considered complete?

[Attila Lendvai]

> We currently include all the dependencies to run the tests, why not do
> the same for documentation building?
> 
> Should we make it a requirement or goal to always package a given package's "documentation-inputs"?


i also lack guidance on this.

and i somewhat miss a "test-inputs" field to explicitly mark the dependencies that are only needed to run the tests. this often doubles the native-inputs dependencies of python packages.

then the infrastructure could be smartened up to not require those dependencies when the tests are disabled for a package. it could serve as a temporary bandaid to fix/upgrade a package while there are some issues with the dependencies needed to run the tests.

i guess same applies to documentation.

some brainstorm follows: but what should be the way to control this for documentation? package arguments, like #:tests? #f for tests? or some way to mark some of the outputs as optional, and a way to request the optional outputs? how would the latter apply to tests, that have no package output? is the anomaly justified?

-- 
• attila lendvai
• PGP: 963F 5D5F 45C7 DFCD 0A39
--
“To every man is given the key to the gates of heaven; the same key opens the gates of hell.

And so it is with science.”
	— Richard Feynman (1918–1988)

Re: Should a Guix package include documentation dependencies to be considered complete?

[Akib Azmain Turja]

[-- Attachment #1: Type: text/plain, Size: 1179 bytes --]

jgart <jgart@dismail.de> writes:

> Hi Guixers,
>
> For example,
>
> https://github.com/Abjad/abjad/blob/63520b2a00ef59f3302837f843d069c3946baa6c/docs/Makefile#L113
>
> We have abjad packaged but we don't necessarily have all the
> dependencies needed to build everything that abjad provides such as a
> PDF document that it mentions in its project Makefile.
>
> Should we include the LaTeX dependencies in the abjad package?
>
> Should all Python packages include the required dependencies to build documentation?
>
> We currently include all the dependencies to run the tests, why not do
> the same for documentation building?
>
> Should we make it a requirement or goal to always package a given package's "documentation-inputs"?
>
> There's another thread where I already talked on this topic with roptat
> briefly. I'll find it and link it soon.
>

Is it just limited to the documentation files, or does it also include
softwares needed to read them?

-- 
Akib Azmain Turja, GPG key: 70018CE5819F17A3BBA666AFE74F0EFA922AE7F5
Fediverse: akib@hostux.social
Codeberg: akib
emailselfdefense.fsf.org | "Nothing can be secure without encryption."

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: Should a Guix package include documentation dependencies to be considered complete?

[Vagrant Cascadian]

[-- Attachment #1: Type: text/plain, Size: 2040 bytes --]

On 2022-12-07, jgart@dismail.de wrote:
> We have abjad packaged but we don't necessarily have all the
> dependencies needed to build everything that abjad provides such as a
> PDF document that it mentions in its project Makefile.
>
> Should we include the LaTeX dependencies in the abjad package?
>
> Should all Python packages include the required dependencies to build documentation?

With my Reproducible Builds hat on...

Some of the main remaining reproducibility issues in Debian are with
documentation generation, notably .pdf and various non-determinism
issues in sphinx, frequently used to generate documentation in various
formats in python projects.

I would hate to have a policy to always generate documentation if it
makes Guix less reproducible... maybe putting the documentation into a
separate output at least? While unreproducible documentation is
unfortunate, it is not that same as, say, the kernel or important core
libraries.

I personally have a strong preference for formats that are largely
readable as "plain" text (markdown, restructuredtext) to fancy
formatting; you can just copy them into the package rather than having
to transform them into some fancy format. I also get that that does not
work for everyone...


> We currently include all the dependencies to run the tests, why not do
> the same for documentation building?
>
> Should we make it a requirement or goal to always package a given package's "documentation-inputs"?

Systematically and programatically being able to distinguish between
"regular" inputs and test and documentation inputs sounds useful in a
number off ways... my only worry would be when a particular input might
shift from one category to another without noticing, and keeping track
of those changes, and maybe cross building would be something to
consider as well. But the advantages might outweigh the disadvantages.

In Debian there is a concept of build profiles (e.g. nocheck, nodoc)
which alter which dependencies are required to build the package.


live well,
  vagrant

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]