Repository: pdfbox-docs Updated Branches: refs/heads/master dd95b2e8e -> 442881561
PDFBOX-3040: update info to build website Project: http://git-wip-us.apache.org/repos/asf/pdfbox-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/pdfbox-docs/commit/44288156 Tree: http://git-wip-us.apache.org/repos/asf/pdfbox-docs/tree/44288156 Diff: http://git-wip-us.apache.org/repos/asf/pdfbox-docs/diff/44288156 Branch: refs/heads/master Commit: 44288156198664c3b2bab5859de99635657215bc Parents: dd95b2e Author: Maruan Sahyoun <sahy...@fileaffairs.de> Authored: Fri Oct 30 13:32:03 2015 +0100 Committer: Maruan Sahyoun <sahy...@fileaffairs.de> Committed: Fri Oct 30 13:32:03 2015 +0100 ---------------------------------------------------------------------- content/siteupdate.md | 81 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 75 insertions(+), 6 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/pdfbox-docs/blob/44288156/content/siteupdate.md ---------------------------------------------------------------------- diff --git a/content/siteupdate.md b/content/siteupdate.md index 0316c7f..0fd2099 100644 --- a/content/siteupdate.md +++ b/content/siteupdate.md @@ -1,15 +1,62 @@ --- -layout: default -title: Updating the Website +license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +layout: default +title: Updating the Website --- -# Update the JavaDocs for PDFBOX 2.x +# Updating the PDFBox Website + +The content for the PDFBox website is kept in a [git repository](https://git-wip-us.apache.org/repos/asf/pdfbox-docs) which is also mirrored to [GitHub](https://github.com/apache/pdfbox-docs). The site is split into two parts: the static content and the Javadoc for the PDFBox API. Both parts are build independently as further described below. + +## Project info +The site is based on [Jekyll](http://jekyllrb.com). So you have to be familiar with the [Markdown](http://daringfireball.net/projects/markdown/syntax) template language and have Jekyll (ver. 2+) installed to contribute to the project. ## Contribute -If you would like to submit a javadoc patch through Jira, please open a ticket at our [Issue Tracker](https://issues.apache.org/jira/browse/PDFBOX) and use `Documentation` for the `Component`. +If you would like to enhance the website content you can submit a patch. To do so please open a ticket at our [Issue Tracker](https://issues.apache.org/jira/browse/PDFBOX), use `Documentation` for the `Component` and add your patch to the ticket. -## Publish (for committers only) -To publish the javadocs follow these steps: +## Development + +### Install Jekyll +Follow the instructions available on the [Jekyll](http://jekyllrb.com) website. + +### Check out from the git repository +Before you can edit the site, you need to check it out from the git repository: + +~~~ +git clone https://git-wip-us.apache.org/repos/asf/pdfbox-docs +~~~ + +### Local changes +You can now do the changes and additions to the sources of the PDFBox website. To test these locally use + +~~~ +jekyll serve +~~~ + +which will compile the changes and run a local webserver at + +~~~ +http://localhost:4000 +~~~ + +### Publish the website (for comitters only) +After you have done the local changes follow these steps to publish the content: Add the following server configuration in your ~/.m2/settings.xml file @@ -23,10 +70,32 @@ Add the following server configuration in your ~/.m2/settings.xml file <p class="alert alert-warning">The password should be encrypted following <a href="https://maven.apache.org/guides/mini/guide-encryption.html";>Maven Password Encryption</a></p> +Ensure that the new website content is build locally + +~~~~ +jekyll build +~~~ + +This will read the sources and generate the new content in the ``./staging`` directory. + +Upload the new content to the production site + +~~~ +mvn scm-publish:publish-scm +~~~ + +This will checkout the current content into the ``./target``directory, apply the changes from ``./staging`` and publish +the changes to the PDFBox production website. + +### Update the JavaDocs for PDFBOX 2.x +To publish the javadocs follow these steps: + Run $ mvn clean javadoc:aggregate scm-publish:publish-scm from the `<SVN_ROOT>/../pdfbox` directory. +It uses the same `pdfbox-site` settings from above to connect to the repository. + <p class="alert alert-info">As <code>mvn clean</code> will delete the javadoc files download from the Apache CMS it's advised to configure <code>${svn.scmJavadocCheckoutDirectory}</code> to a local directory not below <code>./target</code>.</p> \ No newline at end of file
