Bug 695545 - RFE: make doc root configurable
RFE: make doc root configurable
Status: CLOSED CURRENTRELEASE
Product: Publican
Classification: Community
Component: publican (Show other bugs)
2.5
Unspecified Unspecified
unspecified Severity unspecified
: 3.0
: ---
Assigned To: Jeff Fearn
Ruediger Landmann
:
Depends On:
Blocks: 820023
  Show dependency treegraph
 
Reported: 2011-04-11 19:08 EDT by Ruediger Landmann
Modified: 2012-10-30 23:11 EDT (History)
5 users (show)

See Also:
Fixed In Version: 3.0.0
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2012-10-30 23:11:07 EDT
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Ruediger Landmann 2011-04-11 19:08:50 EDT
Description of problem:
Publican documentation packages all install into the one directory: <webroot>/docs. This means that only one documentation site can be served from a machine.

If the doc root were configurable, a server could host multiple documentation sites; for example, for different product lines. This would significantly improve navigation on large documentation sites. 

Version-Release number of selected component (if applicable):
2.5

How reproducible:
100%

Steps to Reproduce:
1. Build a web SRPM
2. Inspect spec file
  
Actual results:
Note:
%define wwwdir %{_localstatedir}/www/html/docs 
and
cp -rf publish/en-US $RPM_BUILD_ROOT/%{wwwdir}/.

Expected results:
Make wwwdir configurable in the config file

Additional info:
We'd also need to be able to generate separate databases for different sites
Comment 1 Jeff Fearn 2011-04-15 01:20:55 EDT
The problem with this is that it requires knowledge of the web site structure by the author before books can be built.

The correct solution would involve building relocatable packages, http://www.rpm.org/max-rpm/s1-rpm-reloc-building-relocatable.html

Not sure this will be in Publican 3.0
Comment 2 Stephen Gordon 2011-04-15 01:52:15 EDT
In the particular use case that led us to this we would know the location. The scenario is that for an up-coming release it has been requested that we not only deploy docs to docs.redhat.com but also along with the application. It is envisaged this will allow the html documentation to be used in providing context sensitive help.

The application in question runs on JBoss, as such they have a directory under the JBoss installation which is effectively their wwwroot and that is where they wish to deploy the docs. This location is understood to be fixed but obviously is different from the /var/www/html/docs directory into which the docs web RPMs deploy currently.
Comment 3 Jeff Fearn 2011-04-15 02:13:53 EDT
Ah I see, application specific sites are doable, although we may have to tweak package names and the like.
Comment 4 Jeff Fearn 2011-04-18 22:23:27 EDT
It occurs to me that the biggest question here is what OS is this intended for?

If the target is RHEL 4/5 then we need to be able to add the entire Publican stack in to a brew root for those OS's.

If the target is RHEL 6 then we will need to be able to update the version of Publican in RHEL 6, or add the entire Publican stack in to another brew root where we can ship an updated Publican.

The reason for this is that the web site packages require Publican on the system they are being installed on to.

Perhaps a better option would be to allow the desktop packages to switch formats. e.g. instead of it containing html-desktop it could contain the eclipse output, or HTML chunked, instead.

Since the desktop packages created in docs-5E do not require publican on the end users system, this would alleviate the need to get an updated Publican shipped.
Comment 5 Stephen Gordon 2011-04-18 22:58:59 EDT
Currently builds are occurring on RHEL5 due to delays in another dependency being ready for RHEL6 but the ultimate target is RHEL6. We are aware of the brew root requirements to be able to distribute the web packages and PM have been made aware of this as well. Ultimately however I'm a big fan of the path of least resistance...

As you've probably guessed the reason the web packages were chosen is primarily that they provide the chunked html output which is more conducive to context sensitive help than the html-single output format. If as you suggest we could allow switching of formats that are built in the desktop packages then this would I believe fulfill our needs.

As noted we would still need to either create or update a RHEL 6 brew root with the updated version of publican in it to build these packages but this would alleviate the need to get it shipped to customers.
Comment 6 Jeff Fearn 2011-04-19 02:27:56 EDT
I'm thinking that this level of customisation really requires the team concerned to manage their own packaging. Automating arbitrary rules in an upstream system is asking for headaches.

e.g. there is nothing stopping any package from using publican to build their docs, in any format, and then just stuffing them wherever they see fit.

BuildRequires: publican publican-BRAND

%build
cd MYBOOK && publican build --etc --etc

%install
cp -rf MYBOOK/tmp/en-US/html $BUILD_ROOT/a/ver/log/path/.

%files
/a/ver/log/path/html

Firther thought required!
Comment 7 Jeff Fearn 2011-04-19 23:21:39 EDT
Added 3 new parameters that can be set in brands to control the configuration of web site packages.

web_dir: The full path to where files will be installed.

web_cfg: The full path to the Publican site config file.

web_req: The name of the RPM package that will supply the Publican site config file.


The rationale behind limiting these fields to brands is that this is a system level task and should not be controlled at the book level.

Committed revision 1763.
Comment 8 Jared MORGAN 2012-05-08 00:16:32 EDT
(In reply to comment #7)
> Added 3 new parameters that can be set in brands to control the configuration
> of web site packages.
> 
> web_dir: The full path to where files will be installed.
> 
> web_cfg: The full path to the Publican site config file.
> 
> web_req: The name of the RPM package that will supply the Publican site config
> file.
> 
> 
> The rationale behind limiting these fields to brands is that this is a system
> level task and should not be controlled at the book level.
> 
> Committed revision 1763.

So to QE verify this, the tester would need to:

1. Make a custom brand according to [1].
2. Set the parameters above according to the guidance provided.
3. Build a publican site and test the functionality.

[1] - http://jfearn.fedorapeople.org/en-US/Publican/2.7/html-single/Users_Guide/index.html#sect-Users_Guide-Files_in_the_brand_directory

I've also observed that the parameters mentioned are not present in any staged version of the Publican User Guide. These probably need to be documented as part of this issue, before being marked as VERIFIED?
Comment 9 Jeff Fearn 2012-05-08 03:20:03 EDT
(In reply to comment #8)
> I've also observed that the parameters mentioned are not present in any staged
> version of the Publican User Guide. These probably need to be documented as
> part of this issue, before being marked as VERIFIED?

Oh we don't have a process for updating the PUG from RFE's ... How about we make one?

My suggestion:

1: Create a BZ for updating the PUG for version X.Y.
2: When an RFE bug gets verified we change the status to verified and link the RFE bug to the PUG update bug.
3: We assign the PUG update bug to Rudi :D

Step 2 could be a 'See Also' or a 'Blocks', as long as the person doing the PUG update knows they need to document something.
Comment 10 Jared MORGAN 2012-05-08 18:58:02 EDT
(In reply to comment #9)
> (In reply to comment #8)
> > I've also observed that the parameters mentioned are not present in any staged
> > version of the Publican User Guide. These probably need to be documented as
> > part of this issue, before being marked as VERIFIED?
> 
> Oh we don't have a process for updating the PUG from RFE's ... How about we
> make one?
> 
> My suggestion:
> 
> 1: Create a BZ for updating the PUG for version X.Y.
> 2: When an RFE bug gets verified we change the status to verified and link the
> RFE bug to the PUG update bug.
> 3: We assign the PUG update bug to Rudi :D
> 
> Step 2 could be a 'See Also' or a 'Blocks', as long as the person doing the PUG
> update knows they need to document something.

I think your suggestion works well, Jeff.

Have an umbrella ticket for all PUG 3.0 issues derived from RFE, or other enhancements that add parameters or undocumented functionality. I like the idea of linking other BZ issues into the main ticket as the primary tracker. 

I think Blocks would be the correct status to set for linked bugs: the status of the bug would be reflected with strikethrough once it was completed (or ready to document). 

If the person documenting the issue has any questions, they ask the questions in the linked development RFE to keep the info together (rather than in the PUG 3.0 umbrella ticket).

I'll get the ball rolling on this.
Comment 11 Michael Hideo 2012-06-07 21:24:38 EDT
(In reply to comment #7)
> Added 3 new parameters that can be set in brands to control the
> configuration of web site packages.
> 
> web_dir: The full path to where files will be installed.
> 
> web_cfg: The full path to the Publican site config file.
> 
> web_req: The name of the RPM package that will supply the Publican site
> config file.
> 
> 
> The rationale behind limiting these fields to brands is that this is a
> system level task and should not be controlled at the book level.
> 
> Committed revision 1763.

need to create custom brand. can be tested locally.
Comment 12 Dan Macpherson 2012-06-15 21:40:58 EDT
I got a fail upon packaging the brand, specifically at %install.

---

Output:

Executing(%install): /bin/sh -e /var/tmp/rpm-tmp.cCJppi
+ umask 022
+ cd /home/dmacpher/Books/publican-test/publican-mybrand/tmp/rpm
+ '[' /home/dmacpher/rpmbuild/BUILDROOT/publican-mybrand-0.1-0.fc17.x86_64 '!=' / ']'
+ rm -rf /home/dmacpher/rpmbuild/BUILDROOT/publican-mybrand-0.1-0.fc17.x86_64
++ dirname /home/dmacpher/rpmbuild/BUILDROOT/publican-mybrand-0.1-0.fc17.x86_64
+ mkdir -p /home/dmacpher/rpmbuild/BUILDROOT
+ mkdir /home/dmacpher/rpmbuild/BUILDROOT/publican-mybrand-0.1-0.fc17.x86_64
+ cd publican-mybrand-0.1
+ LANG=C
+ export LANG
+ unset DISPLAY
+ rm -rf /home/dmacpher/rpmbuild/BUILDROOT/publican-mybrand-0.1-0.fc17.x86_64
+ mkdir -p -m755 /home/dmacpher/rpmbuild/BUILDROOT/publican-mybrand-0.1-0.fc17.x86_64/usr/share/publican/Common_Content
+ publican install_brand --path=/home/dmacpher/rpmbuild/BUILDROOT/publican-mybrand-0.1-0.fc17.x86_64/usr/share/publican/Common_Content
+ mkdir -p -m755 /home/dmacpher/rpmbuild/BUILDROOT/publican-mybrand-0.1-0.fc17.x86_64/ select=/
/var/tmp/rpm-tmp.cCJppi: line 40: xsl:value-of: No such file or directory
error: Bad exit status from /var/tmp/rpm-tmp.cCJppi (%install)

---

mybrand's defaults.cfg:

# Config::Simple 4.59
# Sat Jun 16 11:28:33 2012

doc_url: "http://www.SETUP.example.com/docs"
prod_url: "http://www.SETUP.example.com"

web_dir: /home/dmacpher

----

Moving back to ASSIGNED.
Comment 13 Dan Macpherson 2012-06-16 00:54:37 EDT
^^ Checked publican-3.0-0.fc17.t180.noarch on Fedora 17
Comment 14 Dan Macpherson 2012-06-16 00:57:39 EDT
Documentation required for new params in comment #7.
Comment 15 Ruediger Landmann 2012-06-20 00:00:31 EDT
Need to retest this one and confirm result; maybe failed for an unrelated reason?
Comment 16 Jeff Fearn 2012-06-24 06:25:42 EDT
Creating a brand from scratch and setting web_dir in publican.cfg and wwwdir in the brands spec file works for me from HEAD.

Not sure I ever pointed out that because the brands spec file isn't regenerated at package time it must be manually updated with the directory change.
Comment 17 Ruediger Landmann 2012-06-29 01:18:00 EDT
Verified in build 3.0.t197

Note You need to log in before you can comment on or make changes to this bug.