> On 4 Jan 2015, at 11:35, Maruan Sahyoun <[email protected]> wrote: > > >> P.S. I managed to publish a small change as a test, using the web-based CMS. >> But I’d like to understand (and document?) the complete template and build >> setup. >> > > Great. > > WRT the documentation. There is nothing special on our setup i.e. we are > using the 'regular' Apache CMS build system. So the documentation at > http://www.apache.org/dev/cmsref.html applies. > > To give you a quick overview: > > Everytime there is a change to the svn source tree a build is triggered: > > - looking at lib/path.pm to match the entries in content against the > expressions in path.pm. First match wins. > - from path.pm selecting the view in lib/view.pm > - from view.pm selecting the template in templates/ > - the templates consisting of the html source with django template expression > for logic [https://docs.djangoproject.com/en/1.7/topics/templates/] > > Is there something specific you are looking for?
I’m trying to understand how our JavaDoc gets published, and how the new docs on git will be published in the future. > BR > > Maruan > >> -- John >> >>> On 3 Jan 2015, at 16:59, John Hewson <[email protected]> wrote: >>> >>> >>> >>>> On 2 Jan 2015, at 22:47, Maruan Sahyoun <[email protected]> wrote: >>>> >>>> Am 03.01.2015 um 04:21 schrieb John Hewson <[email protected]>: >>>> >>>>> >>>>> >>>>>> On 2 Jan 2015, at 16:25, Maruan Sahyoun <[email protected]> wrote: >>>>>> >>>>>>> >>>>>>> >>>>>>>> On 1 Jan 2015, at 22:23, Maruan Sahyoun <[email protected] >>>>>>>> <mailto:[email protected]>> wrote: >>>>>>>> >>>>>>>> Hi John, >>>>>>>> >>>>>>>>> >>>>>>>>>> On 1 Jan 2015, at 14:40, Maruan Sahyoun <[email protected] >>>>>>>>>> <mailto:[email protected]> <mailto:[email protected] >>>>>>>>>> <mailto:[email protected]>>> wrote: >>>>>>>>>> >>>>>>>>>> >>>>>>>>>>> This isn’t a good situation at all, we had a usable documentation >>>>>>>>>>> system in October and now we have nothing usable, with almost no >>>>>>>>>>> content and no way to easily contribute. >>>>>>>>>> >>>>>>>>>> how is the content different from the existing one? There wasn't a >>>>>>>>>> lot of content and there still isn't. That usable documentation >>>>>>>>>> system wasn't used a lot. >>>>>>>>> >>>>>>>>> Most of the website is missing, all we have is the cookbook. There’s >>>>>>>>> no way to build, deploy or preview anything. >>>>>>>>> >>>>>>>> >>>>>>>> it's not meant to replace the whole website. That will still reside in >>>>>>>> the Apache CMS which will pull the docs sources from GitHub (I >>>>>>>> explained that in a ticket). >>>>>>> >>>>>>> Do you mean PDFBOX-2340? I assumed that “pdfbox docs” meant our entire >>>>>>> website. I guess not. So this means we have some of the website on SVN >>>>>>> and some of it on Git? And no single revision number for the overall >>>>>>> site? >>>>>> >>>>>> The discussion before pdfbox-docs has been created was to have the >>>>>> documentation on git not the overall website. The build system ist still >>>>>> the Apache CMS as is currently in use. That will have the templates, the >>>>>> build scripts …. - as is today. >>>>>> >>>>>>> >>>>>>>> pdfbox-docs will hold the sources for the documentation. I brought the >>>>>>>> cookbook entries so one can see some of the structure. >>>>>>> >>>>>>> What about the other existing docs? How do I contribute to those? On >>>>>>> SVN? >>>>>>> >>>>>>>>>> >>>>>>>>>>> We’d agreed that moving to docs to GitHub was an experiment to see >>>>>>>>>>> if it made contributing easier but it’s had the opposite effect, >>>>>>>>>>> we’re in a less usable state than ever. It seems like we’d be >>>>>>>>>>> better off going back to our working SVN documentation and creating >>>>>>>>>>> a new 2.0 branch from the 1.8 docs and then updating them. We just >>>>>>>>>>> haven’t realised the benefit from doing things differently. >>>>>>>>>> >>>>>>>>>> There were no major contributions to the documentation using SVN. >>>>>>>>>> Everybody could have done it before but didn't. The non existing >>>>>>>>>> content is not because of GitHub (or SVN). >>>>>>>>> >>>>>>>>> If there’s no advantage to using GitHub then we probably shouldn’t >>>>>>>>> use it. This was a test to see if there were benefits… but there seem >>>>>>>>> to be none. >>>>>>>>> >>>>>>>>>> So my suggestion is to put the content you are planning to >>>>>>>>>> contribute into pdfbox-docs. Now if you put it into the CMS fine. We >>>>>>>>>> can later make it available in pdfbox-docs. >>>>>>>>> >>>>>>>>> I’d like to do that, but unless I need to be able to build and deploy >>>>>>>>> the docs to the website somehow. >>>>>>>>> >>>>>>>>>> I take some of the blame as I didn't find the time to >>>>>>>>>> enhance/restructure the website - again that's not GitHubs fault. >>>>>>>>> >>>>>>>>> Enhancements are of course welcome, but we need the old functionality >>>>>>>>> working, at a bare minimum. e.g. where has most of the website gone? >>>>>>>>> >>>>>>>> >>>>>>>> the restructuring is necessary because the pull mechanism needs to be >>>>>>>> enabled. >>>>>>>> >>>>>>>> In addition there needs to be the place for the PDFBox 2 docs together >>>>>>>> with the old 1.8 docs. That's independent from using SVN or GitHub. >>>>>>> >>>>>>> All we need is a branch in SVN. There’s no need to put the 1.8 docs on >>>>>>> GitHub, they’re going to obsolete in a few months. The simplest >>>>>>> possible solution is to just create a new 2.0 docs branch on SVN. >>>>>>> >>>>>> >>>>>> That's revisiting the git/svn discussion. If there is agreement that it >>>>>> shall stay on SVN fine. >>>>>> >>>>>>>> I have a little more time now so can look into that (and put the >>>>>>>> AcroForm stuff to the side for the moment). OTOH if you or someone >>>>>>>> else wants to do it let me know. >>>>>>> >>>>>>> I’m a little stuck to be honest, it seems that our documentation system >>>>>>> is currently non-functional and part of it is on git for no clear >>>>>>> reason… >>>>>>> >>>>>> >>>>>> We had the git discussion before pdfbox-docs has been created. If we >>>>>> want to revisit that we can always do. >>>>>> >>>>>> Other than that there is a functional documentation system. You can add >>>>>> to the documentation today using svn only or together with pdfbox-docs, >>>>>> do a local build for testing and submit your changes. >>>>> >>>>> What is the workflow for updating pdfbox-docs and pushing it to the >>>>> website? If I make a change to pdfbox-docs what else do I have to do to >>>>> get that published on the website? >>>> >>>> Assuming that the templates, references, scripts are in place you'd have >>>> to trigger the Apache CMS build which will regenerate the website (pulling >>>> the pdfbox-docs sources) and publish it to the staging website. From there >>>> you'd have to publish to the production website. The Apache CMS always >>>> builds to staging. >>>> >>>> You could also use an external build system for the pdfbox-docs files and >>>> from there push the files to the Apache CMS svn tree or upload a >>>> compressed archive. Again this will trigger a build to staging. Uploading >>>> an archive is how we publish the PDFBox javadoc files. >>>> >>>> If you'd like to update production directly you need to build >>>> independently from the Apache CMS and push to the production tree. There >>>> needs to be a configuration file (extpaths.txt) in the Apache CMS which >>>> will tell the Apache CMS to not overwrite that part of the tree. >>>> >>>> A more complete description of the possibilities is in >>>> http://www.apache.org/dev/cmsref.html#external-build. >>> >>> There seem to be a lot of options and customisations possible with the >>> Apache CMS. Do we have a step-by-step workflow documented anywhere >>> specifically describing how the pdfbox website is currently being managed? >>> >>>>> >>>>>> Now there is no sample doing it this way in the PDFBox CMS sources as I >>>>>> didn't have the time yet to create one. The Apache CMS capabilities are >>>>>> documented at http://www.apache.org/dev/cmsref.html >>>>>> <http://www.apache.org/dev/cmsref.html>. Some of the more advanced >>>>>> capabilities are not well documented but need to be gathered by >>>>>> inspecting the code or looking at other projects using the Apache CMS. >>>>>> >>>>>> BTW no need to wait for me doing these changes as every committer has >>>>>> access. >>>>>> >>>>>> BR >>>>>> Maruan >>>>>> >>>>>>>> BR - Maruan >>>>>>>> >>>>>>>>>> Maruan >>>>>>>>>> >>>>>>>>>> >>>>>>>>>>> >>>>>>>>>>> -- John >>>>>>>>>>> >>>>>>>>>>>> On 1 Jan 2015, at 12:52, Maruan Sahyoun <[email protected]> >>>>>>>>>>>> wrote: >>>>>>>>>>>> >>>>>>>>>>>> the docs shall reside in pdfbox-docs from where they will be >>>>>>>>>>>> pulled onto the website or looked at directly at github. >>>>>>>>>>>> >>>>>>>>>>>> The publishing process to our website is not yet in place as there >>>>>>>>>>>> is no new content. I'm looking to get the redesign of the website >>>>>>>>>>>> done to accommodate for the old 1.8 and new 2.0 release. >>>>>>>>>>>> >>>>>>>>>>>> Maruan >>>>>>>>>>>> >>>>>>>>>>>> Am 01.01.2015 um 19:38 schrieb John Hewson <[email protected]>: >>>>>>>>>>>> >>>>>>>>>>>>> Hi All, >>>>>>>>>>>>> >>>>>>>>>>>>> We’re getting closer to 2.0 being ready and I’m thinking about >>>>>>>>>>>>> writing some docs, but currently the situation seems to be worse >>>>>>>>>>>>> than it was before the docs stated moving to GitHub - where are >>>>>>>>>>>>> our canonical docs and how can I contribute to them? >>>>>>>>>>>>> >>>>>>>>>>>>> All I see on GitHub is some old 1.8 stuff and an incomplete >>>>>>>>>>>>> cookbook for forms. Is this content live anywhere? Is there a pay >>>>>>>>>>>>> to preview it? >>>>>>>>>>>>> >>>>>>>>>>>>> -- John >> >
