Hi John,
Am 04.01.2015 um 22:05 schrieb John Hewson <j...@jahewson.com>: > >> On 4 Jan 2015, at 11:35, Maruan Sahyoun <sahy...@fileaffairs.de> 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. JavaDoc: that's currently a manual process. I'm creating the directory, and upload a tarball -> http://www.apache.org/dev/cmsref.html#generated-docs git docs: we are not there yet - basically you can reference svn and git repositories from within the Apache CMS. Unfortunately this is not well documented. The documentation for that feature refers to the Apache Thrift project which is using that. See the discussion about the feature implementation. http://grokbase.com/t/thrift/dev/143gp141d0/reconsidering-the-apache-cms BR Maruan > >> BR >> >> Maruan >> >>> -- John >>> >>>> On 3 Jan 2015, at 16:59, John Hewson <j...@jahewson.com> wrote: >>>> >>>> >>>> >>>>> On 2 Jan 2015, at 22:47, Maruan Sahyoun <sahy...@fileaffairs.de> wrote: >>>>> >>>>> Am 03.01.2015 um 04:21 schrieb John Hewson <j...@jahewson.com>: >>>>> >>>>>> >>>>>> >>>>>>> On 2 Jan 2015, at 16:25, Maruan Sahyoun <sahy...@fileaffairs.de> wrote: >>>>>>> >>>>>>>> >>>>>>>> >>>>>>>>> On 1 Jan 2015, at 22:23, Maruan Sahyoun <sahy...@fileaffairs.de >>>>>>>>> <mailto:sahy...@fileaffairs.de>> wrote: >>>>>>>>> >>>>>>>>> Hi John, >>>>>>>>> >>>>>>>>>> >>>>>>>>>>> On 1 Jan 2015, at 14:40, Maruan Sahyoun <sahy...@fileaffairs.de >>>>>>>>>>> <mailto:sahy...@fileaffairs.de> <mailto:sahy...@fileaffairs.de >>>>>>>>>>> <mailto:sahy...@fileaffairs.de>>> 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 <sahy...@fileaffairs.de> >>>>>>>>>>>>> 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 <j...@jahewson.com>: >>>>>>>>>>>>> >>>>>>>>>>>>>> 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 >>> >> >
