#2864 closed defect (fixed)

docs.rtems.org Automatic update of branches content when a rtems-doc.git change is made.

Reported by: Chris Johns Owned by:
Priority: high Milestone: 5.1
Component: doc Version: 5
Severity: major Keywords:
Cc: Blocked By:
Blocking:

Description

Add support to automatically update the branches when a git commit happens.

Change History (12)

comment:1 Changed on Jan 16, 2017 at 6:00:41 AM by Amar Takhar

You mean automatically build the docs when someone makes a commit to them?

A little confused by the description. :)

comment:2 in reply to:  1 Changed on Jan 16, 2017 at 6:23:20 AM by Chris Johns

Summary: docs.rtems.org Automatic update of branches.docs.rtems.org Automatic update of branches content when a rtems-doc.git change is made.

Replying to amar:

You mean automatically build the docs when someone makes a commit to them?

Yes and publish the build on the docs.rtems.org website. The website is driven off an XML catalogue created when building the docs so document changes, additions, renames and removals are handled within the built package.

A little confused by the description. :)

Sorry, I have amended the Summary. I hope this is better.

I intend to build on sync.rtems.org when a hash on a branch changes, tar the content then transfer to docs.rtems.org. I have a script to manage the git hash checking and to build the content. A job on docs will pick up the new package and install it. All I need a way to move the package from sync to docs.

comment:3 Changed on Jan 16, 2017 at 2:09:42 PM by Amar Takhar

I have already written something like this for the new docs.rtems.org. Incremental builds (by commit) and release builds.

It needs to be managed properly, most projects overwrite their 'devel' documentation with new versions. I want to keep around every single built version for comparison this is more useful for contributors.

comment:4 in reply to:  3 ; Changed on Jan 16, 2017 at 10:42:15 PM by Chris Johns

Replying to amar:

I have already written something like this for the new docs.rtems.org. Incremental builds (by commit) and release builds.

Release builds are part of the release process which is a separate from this web site. The released documents are loaded on the the web site and the website's configuration updated to include the release details and the site is regenerated.

For building from git I was told to sort out building by cron so this is what I have done.

Is it possible to set up a share on the TrueNAS to be a clearing house between sync and docs?

It needs to be managed properly, most projects overwrite their 'devel' documentation with new versions.

I am concerned it places extra stress on the limit resources we have so do not see holding builds as a priority. We have the source in git so someone can get that release and build it.

I want to keep around every single built version for comparison this is more useful for contributors.

How is this more useful for contributors?

comment:5 in reply to:  4 ; Changed on Jan 17, 2017 at 12:15:53 AM by Amar Takhar

Replying to chrisj:

Release builds are part of the release process which is a separate from this web site. The released documents are loaded on the the web site and the website's configuration updated to include the release details and the site is regenerated.

They'll all be built from the same location using the same tools and same process the only difference is one will be a tag and the other a branch. If you are talking about what 'triggers' a build then yes they are different.

For building from git I was told to sort out building by cron so this is what I have done.

Is it possible to set up a share on the TrueNAS to be a clearing house between sync and docs?

How long is this going to be setup for? I suggested this before you mentioned building after every commit...

It needs to be managed properly, most projects overwrite their 'devel' documentation with new versions.

I am concerned it places extra stress on the limit resources we have so do not see holding builds as a priority. We have the source in git so someone can get that release and build it.

Space isn't an issue it will be a decade worth of builds before it will be a problem.

The other nice feature is if someone builds from a commit in source they'll have the corresponding documentation available that is as close to that version as possible -- I have a way to track this it's a tool I wrote some time ago.

I want to keep around every single built version for comparison this is more useful for contributors.

How is this more useful for contributors?

Not all errors are build errors some are formatting/syntax. Lots of contributors don't have the ability to build docs from source -- I don't think that is a pre requisit to make changes since they need to be tested before commit anyway.

Docs are unique in that regard.

comment:6 Changed on Jan 17, 2017 at 1:40:43 AM by Joel Sherrill

What is the problem with providing a way to get content from a "build jail" to a "offer to the world jail"? AFAIK all solutions include either making a directory on the TrueNAS available to the "offer to the world jail" or push via ssh. Please help Chris.

Providing this path from "build to "offer to the world" is not an unusual requirement. It is needed for multiple offerings.

There is negative value in keeping builds of documentation on every commit.

comment:7 in reply to:  5 Changed on Jan 17, 2017 at 5:14:41 AM by Chris Johns

Replying to amar:

Replying to chrisj:

Release builds are part of the release process which is a separate from this web site. The released documents are loaded on the the web site and the website's configuration updated to include the release details and the site is regenerated.

They'll all be built from the same location using the same tools and same process the only difference is one will be a tag and the other a branch. If you are talking about what 'triggers' a build then yes they are different.

I am not sure if we are saying the same thing or not.

A release of RTEMS contains released documentation and the formally released procedure creates that tar file of documentation. The rtems-release.git repo contains the format release scripts. Released documentation must be created as part of that formal release procedure.

For building from git I was told to sort out building by cron so this is what I have done.

Is it possible to set up a share on the TrueNAS to be a clearing house between sync and docs?

How long is this going to be setup for?

I am sorry I have no idea how long. I am just wanting to fill a gap that currently exists as best I can. I am after a simple, secure method to complete this task. As Joel says, if a simple solution can be found and this can be done that would be excellent. We would also be free to move on and sort other issues out, eg buildbot of the RTEMS code, new website, etc and we can come back to this when we have time, funding etc. We are working hard and openly to try to get this to happen but is hard.

I suggested this before you mentioned building after every commit...

I did not know sphinx could not be installed on docs.rtems.org and the docs built in that jail. I just assumed the docs could be built on each commit on docs.rtems.org. When I looked at the jail I saw you had installed tex alive and other packages and you had been building documentation there.

It needs to be managed properly, most projects overwrite their 'devel' documentation with new versions.

I am concerned it places extra stress on the limit resources we have so do not see holding builds as a priority. We have the source in git so someone can get that release and build it.

Space isn't an issue it will be a decade worth of builds before it will be a problem.

The other nice feature is if someone builds from a commit in source they'll have the corresponding documentation available that is as close to that version as possible -- I have a way to track this it's a tool I wrote some time ago.

Sorry, I do not follow. How would someone with a local build compare and what would the value be in doing this?

I want to keep around every single built version for comparison this is more useful for contributors.

How is this more useful for contributors?

Not all errors are build errors some are formatting/syntax. Lots of contributors don't have the ability to build docs from source -- I don't think that is a pre requisit to make changes since they need to be tested before commit anyway.

Docs are unique in that regard.

We have been testing on a number of hosts and it builds ok. I have not built PDF on OS X as tex alive is too hard without something like brew or macports, HTML works.

comment:8 Changed on May 11, 2017 at 7:31:02 AM by Sebastian Huber

Milestone: 4.124.12.0

comment:9 Changed on Aug 13, 2017 at 11:40:11 PM by Chris Johns

Version: 4.114.12

comment:10 Changed on Sep 4, 2017 at 1:06:13 AM by Chris Johns

Resolution: fixed
Status: newclosed

Commits update master and the release branch.

comment:11 Changed on Oct 10, 2017 at 6:06:29 AM by Sebastian Huber

Component: Documentationdoc

comment:12 Changed on Nov 9, 2017 at 6:27:14 AM by Sebastian Huber

Milestone: 4.12.05.1

Milestone renamed

Note: See TracTickets for help on using tickets.