On 1/19/22 12:00 PM, Jon Evans wrote:
That just doesn't seem that useful to me. The fact that Fedora forces this
process means that Fedora offline docs will always be outdated.
I don't disagree, but really, we could say that everything is always outdated -
the code, the libs etc. I have to pick a point in time, and create packages as
of that point - currently that point is when a new release is tagged. I.e., it
is a manual process - I have to consciously create the packages, and it then
takes a week or so for the packages to sit in the testing repositories before
being released to general users. I have no control over that process.
If there is no way to work around it for Fedora, I suggest we develop an
out-of-band way of delivering offline docs to people (not using the Fedora
packaging system).
People can always download the nightly docs packages via Copr, which will
correspond to whatever is in the master branch. There is no process at the
moment for nightlies to build from any other branch, although I suppose one
could be added.
Steve
On Wed, Jan 19, 2022 at 11:52 AM Steven A. Falco <[email protected]
<mailto:[email protected]>> wrote:
Right now, the downstream (official) Fedora builds depend on a single tag
for all the components - source code, libraries, and docs.
I could substitute a SHA for the docs, but I'd have to hard-code the SHA in the
"spec file" that controls the build, the same way the tag is hard-coded in the
spec file.
Since all the components are built at the same time from the same script, it would not be
possible to "update every time something is pushed to the V6 branch". I.e., Fedora
builds are not a "rolling release" - they are tied to tags.
Steve
On 1/19/22 11:38 AM, Jon Evans wrote:
> 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 <http://docs.kicad.org> <http://docs.kicad.org <http://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 <[email protected]
<mailto:[email protected]> <mailto:[email protected]
<mailto:[email protected]>>> 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
<https://launchpad.net/~kicad-developers> <https://launchpad.net/~kicad-developers
<https://launchpad.net/~kicad-developers>>
> Post to : [email protected]
<mailto:[email protected]> <mailto:[email protected]
<mailto:[email protected]>>
> Unsubscribe : https://launchpad.net/~kicad-developers
<https://launchpad.net/~kicad-developers> <https://launchpad.net/~kicad-developers
<https://launchpad.net/~kicad-developers>>
> More help : https://help.launchpad.net/ListHelp
<https://help.launchpad.net/ListHelp> <https://help.launchpad.net/ListHelp
<https://help.launchpad.net/ListHelp>>
>
>
> _______________________________________________
> Mailing list: https://launchpad.net/~kicad-developers
<https://launchpad.net/~kicad-developers>
> Post to : [email protected]
<mailto:[email protected]>
> Unsubscribe : https://launchpad.net/~kicad-developers
<https://launchpad.net/~kicad-developers>
> More help : https://help.launchpad.net/ListHelp
<https://help.launchpad.net/ListHelp>
_______________________________________________
Mailing list: https://launchpad.net/~kicad-developers
<https://launchpad.net/~kicad-developers>
Post to : [email protected]
<mailto:[email protected]>
Unsubscribe : https://launchpad.net/~kicad-developers
<https://launchpad.net/~kicad-developers>
More help : https://help.launchpad.net/ListHelp
<https://help.launchpad.net/ListHelp>
_______________________________________________
Mailing list: https://launchpad.net/~kicad-developers
Post to : [email protected]
Unsubscribe : https://launchpad.net/~kicad-developers
More help : https://help.launchpad.net/ListHelp
