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 <stevenfa...@gmail.com> 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 <stevenfa...@gmail.com > <mailto:stevenfa...@gmail.com>> 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.schoen...@t-online.de <mailto:c.schoen...@t-online.de> <mailto: > c.schoen...@t-online.de <mailto:c.schoen...@t-online.de>>> 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@lists.launchpad.net <mailto: > kicad-developers@lists.launchpad.net> <mailto: > kicad-developers@lists.launchpad.net <mailto: > kicad-developers@lists.launchpad.net>> > > > 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@lists.launchpad.net <mailto: > kicad-developers@lists.launchpad.net> > > > 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@lists.launchpad.net <mailto: > kicad-developers@lists.launchpad.net> > > 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 : kicad-developers@lists.launchpad.net Unsubscribe : https://launchpad.net/~kicad-developers More help : https://help.launchpad.net/ListHelp
