kicad-developers team mailing list archive

[Jon Evans <jon@xxxxxxxxxxxxx>]

The way we have split things up now, the nightly docs are not the
appropriate pairing for the V6 stable release -- they may diverge over time.

I think the vast majority of Linux users also have access to the Internet
and so directing them to the most up-to-date docs is the right move.

I am not saying we should remove any way for people in high-security
offline environments to get documentation, but just that it shouldn't be
the default option.

-Jon

On Wed, Jan 19, 2022 at 12:12 PM Steven A. Falco <stevenfalco@xxxxxxxxx>
wrote:

> 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 <stevenfalco@xxxxxxxxx
> <mailto:stevenfalco@xxxxxxxxx>> 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 <
> c.schoenert@xxxxxxxxxxx <mailto:c.schoenert@xxxxxxxxxxx> <mailto:
> c.schoenert@xxxxxxxxxxx <mailto: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 <
> https://launchpad.net/~kicad-developers> <
> https://launchpad.net/~kicad-developers <
> https://launchpad.net/~kicad-developers>>
> >      >     Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx <mailto:
> kicad-developers@xxxxxxxxxxxxxxxxxxx> <mailto:
> kicad-developers@xxxxxxxxxxxxxxxxxxx <mailto:
> kicad-developers@xxxxxxxxxxxxxxxxxxx>>
> >      >     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     : kicad-developers@xxxxxxxxxxxxxxxxxxx <mailto:
> kicad-developers@xxxxxxxxxxxxxxxxxxx>
> >      > 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     : kicad-developers@xxxxxxxxxxxxxxxxxxx <mailto:
> kicad-developers@xxxxxxxxxxxxxxxxxxx>
> >     Unsubscribe : https://launchpad.net/~kicad-developers <
> https://launchpad.net/~kicad-developers>
> >     More help   : https://help.launchpad.net/ListHelp <
> https://help.launchpad.net/ListHelp>
> >
>
>