更新 PDFBox 网站

PDFBox网站的内容保存在Git存储库中，该存储库也镜像到GitHub。该网站分为两部分：静态内容和PDFBox API的Javadoc。这两个部分都是独立构建的，如下所述。

贡献

如果您想增强网站内容，可以提交补丁。为此，请在我们的问题跟踪器中打开一个工单，用于 并将您的补丁添加到工单中。DocumentationComponent

发展

用于生成网站的工具：

  • Git 一个源代码管理工具，用于从不同的文档源获取文档源 GitHub 存储库。
  • Node.js用于构建网站的JavaScript运行时。您将需要使用 Node.js 版本 10。 并管理所需的库。
  • （通过 npm 安装）十一 一个更简单的静态站点生成器。
  • （可选）Maven 一个用于运行完整网站生成过程的构建工具

从 Git 存储库签出

在编辑站点之前，您需要从 Git 存储库中签出它：

git clone https://gitbox.apache.org/repos/asf/pdfbox-docs

本地更改

要构建网站，请转到项目根目录并运行：

$ npm install # needed only once, or if dependencies change
$ npm run build   # to perform the build

预览更改

更改内容时，可以在预览模式下完成网站生成。这将启动一个小的网络服务器，并在有更改时更新浏览器窗口，以便立即反映这些更改。

$ npm install # needed only once, or if dependencies change
$ npm run preview   # to start the preview mode

验证生成的文件

要验证生成的网站文档，请转到项目根目录并运行：

$ npm run checks

重用文档中示例中的代码

为了重用文档中示例项目中的代码，可以使用短代码。codesnippet

简码需要两个变量

  • 示例代码的相对路径，例如interactive/form/CreateCheckBox.java
  • 要使用的版本，例如 或trunk2.0

此外 - 为了能够只将部分代码放入 文档 可以将以下注释添加到 Java 代码中

//DOC-START
...
//DOC-END

DOC-START/DOC-END 对可以多次放入 Java 中 法典。这些特殊注释行之间的所有内容都将添加 其他内容将被省略。这将允许跳过许可证 标头、导入语句等，以专注于重要位。

发布网站（仅适用于提交者）

完成本地更改后，请按照以下步骤发布内容：

在 ~/.m2/settings.xml 文件中添加以下服务器配置

<server>
  <id>pdfbox-site</id>
  <username>** USERNAME **</username>
  <password>** PASSWORD **</password>
</server>

pdfbox-site引用自 PDFBox pom.xml 文件。

密码应按照Maven密码加密进行加密

确保新网站内容可以在本地构建

npm run build

这将读取源并在目录中生成新内容。./staging

当您对新内容感到满意时，请更新源存储库

git commit -m "..."
git push origin master

将新内容上传到生产站点

mvn scm-publish:publish-scm

这会将当前内容签出到目录中，应用更改并发布 对 PDFBox 生产网站的更改。./target./staging

更新 Javadoc for PDFBox

The Javadoc for PDFBox is hosted on javadoc.io which uses the built at release time as a source. javadoc.io also makes older versions of the Javadoc available.pdfbox-<version>-javadoc.jar

In order to update the documentation to match a latest release of a branch

  • update the variable in the matching subdirectories filerelease<version>.11tydata.js
  • update the link(s) in the file_layouts\documentation.html

Build with Maven

The project provides a simple way to build the website sources locally using the build tool Maven.

The Maven build automatically downloads the tool binaries such as and for you. You do not need to install those tools on your host then. The binaries are added to the local project sources only and generate the website content.nodenpm

As the Maven build uses pinned versions of and that are tested to build the website you most likely avoid build errors due to incompatible versions of tooling installed on your machine.nodenpmnode.js

Preparing Maven

Make sure that you have Maven installed.

$ mvn --version

If this command fails with an error, you do not have Maven installed.

Please install Maven using your favorite package manager (like Homebrew) or from official Maven binaries

Building from scratch

When building everything from scratch the build executes following steps:

  • Download and binaries to the local projectNode.jsnpm
  • Load required libraries to the local project using npm
  • Build the website content using Eleventy

You can do all of this with one single command:

$ mvn package

The whole process takes up to five minutes (time to grab some coffee!)

When the build is finished you should see the generated website in the directory.public

Clean build

When rebuilding the website the process uses some cached content. If you want to start from scratch for some reason you can simply add the operation to the build which removes all generated sources in the project first.clean

$ mvn clean package