kicad-developers team mailing list archive

[Jon Evans <jon@xxxxxxxxxxxxx>]

Carsten,

There is no reason to remove the ability to package docs offline, I just
don't think it should be a focus of the project.
The majority of users will be served better by keeping a "rolling release"
online at docs.kicad.org (with a download button, ideally).

> It absolutely doesn't hurt to build completely offline usable
documentation.

It does hurt the way we do it today, for the following reasons:

1) We currently support multiple formats, which makes the build system and
formatting changes complicated

2) We currently tie the documentation version together with the application
version, and don't have good workflows for "rolling release" of
documentation for Linux distros that use separate packages.

3) The application itself doesn't handle the situation where offline docs
are missing very gracefully, or note to users that when offline docs are
present that they are probably outdated.

What I would propose to improve the situation is:

1) Drop all formats except HTML.  HTML is perfectly fine as an offline
format, and this allows us to make improvements to the build workflow and
the layout/style of the docs without worrying about doing so in a way that
also works for PDF.  If you really want a PDF, you can render it from HTML
pages anyway.

2) Change the application to gracefully redirect to the online docs if
offline docs are missing

3) Make a better "offline docs" build that adds the warning about docs
being out-of-date.  Have packagers use this if they want to generate docs
packages, and maybe make it easy for anyone to download these from the
website.

4) Stop tagging the kicad-docs repo with every KiCad code release.
Instead, continue the new practice we have started of maintaining major
release branches for the docs (V5, V6, etc) and have packagers start
packaging the tip of these branches.  I.e. the Ubuntu package for
kicad-docs will update every time something is pushed to the V6 branch as
long as V6 is the stable release, and so on.

-Jon

On Wed, Jan 19, 2022 at 11:29 AM Carsten Schoenert <c.schoenert@xxxxxxxxxxx>
wrote:

> Hello,
>
> Am 19.01.22 um 17:21 schrieb Gabriel Staples, ElectricRCAircraftGuy.com:
> ...
> > In other words, please do make "online documentation" only, as it allows
> > faster updates to it and better consistency,
>
> please don't!
> It absolutely doesn't hurt to build completely offline usable
> documentation. It works for years without special requirements.
>
> I work often in environments where I have absolutely no access to the
> internet, but can use packaged software, so I heavily need offline
> documentation to do some sort of productive work.
>
> --
> Regards
> Carsten
>
> _______________________________________________
> Mailing list: https://launchpad.net/~kicad-developers
> Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~kicad-developers
> More help   : https://help.launchpad.net/ListHelp
>