Bug 956 - Need updated doc publishing process in Makefiles and Yocto Project website
Summary: Need updated doc publishing process in Makefiles and Yocto Project website
Status: RESOLVED FIXED
Alias: None
Product: Quick Start
Classification: Documentation
Component: quick-start (show other bugs)
Version: 1.0
Hardware: Other Multiple
: High critical
Target Milestone: 1.0 PointRelease
Assignee: Saul Wold
QA Contact:
URL:
Whiteboard: Patch pending integration (5-May-2011)
Depends on:
Blocks:
 
Reported: 2011-04-06 08:37 UTC by Scott Rifenbark
Modified: 2011-05-13 10:50 UTC (History)
8 users (show)

See Also:
OS type for building Yocto: ---
Type of Regression: ---
Verified:
Documentation change: ---


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Scott Rifenbark 2011-04-06 08:37:56 UTC
Currently our Makefile structure attempts to publish to 
'o-hand.com:/srv/www.pokylinux.org/doc/'.  This doesn't work and we should 
be pushing to http://yoctoproject.org/docs into the appropriate manual 
directory.  We need to set up the Makefiles with the right URL and have the right permissions going on so that whenever a manual is "made" the HTML version and PDF versions automatically get published to our Yocto Project website doc structure.  This process will make sure the manuals in the website always have the latest information.
Comment 1 Scott Rifenbark 2011-04-22 05:35:54 UTC
Need engineering or IT support to be able to get this going.  Unless I am missing something here the solution seems pretty simple.  Just need some permissions to publish stuff into the drupal site hosting the yocto website.
Comment 2 Jeff Osier-Mixon 2011-04-22 09:10:36 UTC
Hi Scott - Mike may be able to set this up.  I'm assuming the needed permissions are just for you, not for everyone, right?

I had a question, though, about whether it is a good idea to autopublish on every make.  Is there a process to vet the docs before publishing?  In past projects I have set up "make install" to publish the docs, but running "make" just builds locally. Maybe I am misunderstanding the process.
Comment 3 Scott Rifenbark 2011-04-22 09:13:31 UTC
I don't know who the permissions are required for... This is the part I am unfamiliar with.  I would assume that would work though.  

Regarding publishing on every make I don't see a problem with that as that would make sure the docs on the website are always most recent.
Comment 4 Jeff Osier-Mixon 2011-04-22 09:29:35 UTC
I'm still not sure I understand. Every time someone downloads poky and builds it, they publish documentation to the main website? That opens up security concerns in addition to quality concerns.

I would strongly recommend changing the Makefile to require a second step to publish documentation to the main site, and some vetting process. I love transparency and community inclusion, but there has to be some gatekeeping process. Imagine if everyone who downloaded and built the Linux kernel also posted it to kernel.org every time they typed "make".
Comment 5 Scott Rifenbark 2011-04-22 09:45:03 UTC
Good point... I did not think of the world working on the docs.  I was lost in my little closed process of my own.  Maybe I should talk to you and we can think this thing out a bit....
Comment 6 Scott Rifenbark 2011-04-22 10:17:03 UTC
To fix this bug we will remove the publish option from all the documentation make files.  these were publishing to o-hand and were broke anyway.  then we will create a local script that can be executed to push the most recent HTML documentation files to the Yocto Project website.  The local script can be run at our convenience when we are satisfied with the quality of community patches and internal work regarding the docs.
Comment 7 Scott Rifenbark 2011-04-26 09:46:41 UTC
After further discussion with RP it appears that we do not need a separate local script to publish or push the HTML files to the Yocto Project website.  Evidently the ssh key can be used to restrict access to the website.  So, the fix for this bug will be making sure the ssh key and permissions are set up correctly and then changing the publish statements in each document's make file.  They currently attempt to publish to o-hand.  I am waiting on RP's assistance to complete this bug.
Comment 8 Scott Rifenbark 2011-05-05 09:27:00 UTC
Saul and Beth to work with ScottR to get the permissions on the server and the ssh key stuff straightened out and working.  ScottR to make changes to the Makefiles for the manuals.
Comment 9 Beth Flanagan 2011-05-06 08:48:54 UTC
A few things we need to discuss here, Scott.

1. Switching the URL/giving you access can happen today. I'll ping you on IRC
2. That said, the doc publishing has some process issues:
   - We have no history wrt doc publishing. So, for example, we can't go back to, say, laverne docs. Going forward, this needs to be fixed.

We should have something like:

www.yoctoproject.org/documentation/1.0/<docname>
www.yoctoproject.org/documentation/current/<docname> (symlink to most recent documentation)

This will allow us to have docs that support prior releases.

   - We're really talking about two release processes here. You need the ability to update documentation that exists, should a bug be found (like a bug in bernard documentation, for example). You also need the ability to release new documentation (like 1.1). This is fairly easy to accomplish and should be brought into the release process. Let's talk about this. I've put a feature on the 1.1 list to bring this into the release process.
Comment 10 Beth Flanagan 2011-05-06 16:07:32 UTC
I've got the server side of this fixed for the time being. However this should be an rsync, not an scp.

A good portion of the publishing functionality should be brought into the release process. I'm going to open another bug on this to track that portion.
Comment 11 Scott Rifenbark 2011-05-06 16:18:52 UTC
I have the Makefile issues worked out and two of the five manuals are working with the changes pushed to yocto-docs.  I will close on this when the other three manuals are good.
Comment 12 Scott Rifenbark 2011-05-09 11:37:05 UTC
All changes have been committed and pushed to the yocto-docs repo to satisfy this bug.  The publish process for all five YP manuals now works so that when I run it the HTML and PDF versions of the manuals (along with related style sheets and PNG files) are pushed to the Yocto Project website into the appropriate documentation folder structure.  Once the yocto-docs repo is merged with the poky repo by Saul or RP the bug can be closed.