This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new eebc30d update doc build instructions to explain local-build.sh and
related possibilities (#6587)
eebc30d is described below
commit eebc30dccf2a1caf081afbf6f92bf3020ae50578
Author: djencks <djen...@apache.org>
AuthorDate: Thu Dec 23 05:41:06 2021 -0800
update doc build instructions to explain local-build.sh and related
possibilities (#6587)
---
.../ROOT/pages/improving-the-documentation.adoc | 105 ++++++++++-----------
.../modules/ROOT/pages/release-guide-website.adoc | 19 +++-
2 files changed, 67 insertions(+), 57 deletions(-)
diff --git
a/docs/user-manual/modules/ROOT/pages/improving-the-documentation.adoc
b/docs/user-manual/modules/ROOT/pages/improving-the-documentation.adoc
index 223b3db..304845e 100644
--- a/docs/user-manual/modules/ROOT/pages/improving-the-documentation.adoc
+++ b/docs/user-manual/modules/ROOT/pages/improving-the-documentation.adoc
@@ -73,23 +73,40 @@ Preview your work in the Intellij Asciidoc plugin preview
or in a browser with a
//=== Currently usable workflow
. Commit and push your work and create a PR in the (sub)project repository.
. Fork/clone the camel-website repository, and create an appropriate branch,
e.g. `git switch -c camel-quarkus-main-456`.
-. Locate the project you are working with in the `antora-playbook.yml` under
`sources`, and locate the branch you have altered under the appropriate `-url`.
-.. Comment out the original source URL and replace it with the URL of your
fork.
-.. Leaving the original branch as a comment, alter the branch to e.g. `-
main-doc-fix` using your branch name.
-.. Make sure that all other branches used for the documentation are up to date
in your fork.
-To do this, for each such branch, execute
-[source,console]
+The following process will work for any number of doc PRs against any number
of source repositories: usually you will have one subproject repo and one
branch.
+. Locate the `- url` of the project(s) you are working with in the
`antora-playbook.yml` under `sources`, and locate the branch(es) you have
altered under that `- url`.
+. Add something like this to the end of the `antora-playbook.yml`:
++
+--
+[source,yml]
----
-git switch <branch>
-git pull
-git push <fork>
+ - require: '@djencks/antora-source-map'
+# log_level: trace #<1>
+ source-map: <2>
+ - url: 'https://github.com/apache/camel-kamelets.git' # <3>
+ mapped-url: 'https://github.com/djencks/camel-kamelets.git' # <4>
+ branches: # <5>
+ - branch: main # <6>
+ mapped-branch: main-collect # <7>
+ - branch: 0.6.x
+ mapped-branch: 0.6.x-collect
+ - branch: 0.5.x
+ mapped-branch: 0.5.x-collect
----
-. Commit the change to the playbook, push it to your `camel-website` fork, and
open a PR against `camel-website`.
-CI will build your change and, if successful, will deploy a preview on Netlify.
-There will be an email with the preview URL.
+<1> Turning on trace logging will show you in great detail what's changed from
the regular playbook, which can be useful if the build is not doing what you
expect.
+<2> List of source urls to substitute, probably only one.
+<3> The GitHub URL of the subproject you are working on.
+<4> The GitHub URL of your fork of the subproject.
+<5> List of modified branches: probably only one.
+<6> Name of the branch your PR will merge into.
+<7> Name of your PR branch.
+--
+. At this point you can test your playbook changes locally by running `yarn
build:antora` or `yarn build`.
+. Commit the playbook changes, push to your fork of the `camel-website`
repository, and open a PR.
+. If all goes well you will get an email telling you where the Netlify preview
is; this is also shown on the PR page.
. Check for build problems and examine the preview.
. Upon approval, your content PR will be merged.
-Unless you have made a considerably more extensive change than described
above, the `camel-website` PR will not need to be merged and may be closed.
+A `camel-website` PR constructed as described here will not need to be merged
and may be closed.
[#_local_build_instructions]
== How to build the website locally, with your changes
@@ -121,60 +138,36 @@ Run a build against the remote source repos to check that
it works and to build
yarn build-all
----
-=== Adjusting the playbook to include local changes
-
-The Antora build is specified in the `camel-website:antora-playbook.yml`
playbook.
-The content repositories are specified under the `content/sources` key.
-Locate the subproject you are working on and change the `url` to point to the
local checkout of the subproject, e.g.
+NOTE: The following procedure is not available in all subprojects yet.
+If there is no `docs/local-build.sh` in the one you are working on, please
ping djencks on zulip and I'll try to get it in soon.
-[source,yml]
-----
-# - url: https://github.com/apache/camel-quarkus.git <1>
- - url: ./../camel-quarkus <2>
- branches:
- - main
- - 2.5.x
- - 2.4.x
- start_path: docs
-----
-<1> Leaving the original can help setting up the playbook for a PR build.
-<2> This relative path depends on the organization of all your camel projects
in a `camel` directory.
-
-Your local changes will need to be on a branch, so change the branch name, e.g.
-
-[source,yml]
-----
-# - url: https://github.com/apache/camel-quarkus.git
- - url: ./../camel-quarkus
- branches:
-# - main
- - main-doc-fixes
- - 2.5.x
- - 2.4.x
- start_path: docs
-----
+=== Initial full Antora build
-Make sure that every branch used in the documentation is present locally and
up to date.
-In the subproject directory, for each branch, run e.g.
+You only have to do this once, and again whenever there are significant
changes to the website.
-[source, console]
+In your project, run
+[source,sh]
----
-git switch 2.5.x
-git pull
+./local-build.sh full
----
+This will build the entire site, including your changes in your branch, and
generate a 'site-manifest' listing all the contents of the website, that can be
used to build only small parts of the site.
+This full build will also check that all xrefs into your subproject branch are
valid.
-Now you are ready to build your work locally, in `camel-website`:
+=== Subsequent partial continuous builds
-[source, console]
+After this full build completes, you can work on documentation with live
updates in your browser by running
+[source,sh]
----
-yarn build:antora
-# or yarn build to include hugo content.
+./local-build.sh
----
+This will do an initial build of just the current branch in the current
subproject, incorporating it into the full site built in the previous step,
start a web server to serve the site, set up browser-sync on pages you are
looking at in your browser, and rebuild the (partial) site as it detects
changes.
+Depending on the amount of content generation Antora is doing, this may take
up to a minute or so.
-Note that Antora will use the file system state of your main checked-out
branch, whether or not these changes are committed.
-If you have additional git worktrees checked out, you can have Antora use the
file system state of these also, see
https://docs.antora.org/antora/3.0/playbook/content-worktrees/[the Antora
worktrees documentation].
+This partial build will detect broken xrefs within your branch and from your
branch to the main site, but will not (yet) detect broken xrefs from the rest
of the site into your branch.
+If you rename or remove a page please do a full build or check the PR build
carefully for broken xrefs.
-If you do a full build and have Docker available locally you can view your
build served with httpd by running `local-httpd-in-docker.sh`.
+If you do a full build (`yarn build-all` or `yarn build` rather than `yarn
build:antora` or use of the `local-build.sh` script in a subproject) and have
Docker available locally you can view your build served with httpd by running
`local-httpd-in-docker.sh`.
+This is especially valuable to check redirects set up with `page-aliases`.
== New, renamed, or removed pages
diff --git a/docs/user-manual/modules/ROOT/pages/release-guide-website.adoc
b/docs/user-manual/modules/ROOT/pages/release-guide-website.adoc
index 4653637..a4abc54 100644
--- a/docs/user-manual/modules/ROOT/pages/release-guide-website.adoc
+++ b/docs/user-manual/modules/ROOT/pages/release-guide-website.adoc
@@ -63,6 +63,23 @@ These represent the other camel subprojects this one depends
on.
** For subprojects in the same release set, such as `camel`,
`camel-spring-boot`, and `camel-karaf`, these versions will need to be updated
to refer to the new version of the other subproject.
. Remove `prerelease` from `asciidoc/attributes`.
. If the release is LTS, add an `lts` attribute specifying the date out of
service.
+. Find the `source-map.yml` file next to the `antora.yml` component descriptor.
+It will look something like this:
++
+--
+[source,yml]
+----
+ - require: '@djencks/antora-source-map'
+# log_level: trace
+ source-map:
+ - url: 'https://github.com/apache/camel-kamelets.git'
+ mapped-url: './../camel-kamelets'
+ branches:
+ - branch: main
+ mapped-branch: HEAD
+----
+--
+Change the `- branch: main` to specify the branch being released, e.g. `-
branch: 0.6.x`.
. Build each project (e.g. `mvn clean install -Pfastinstall`) and check for
generated changes that need to be committed (or undone if there are tooling
problems).
Since the branches with these changes have not yet been added to the Antora
playbook, they may be kept on a PR fork/branch or merged into the release
branch locally or in the repository.
@@ -76,7 +93,7 @@ These changes must go through a PR before being merged, and
it is highly advisab
Note that this is the git branch name, which is related to but usually not
identical to the Antora component version.
. Consult these
xref:improving-the-documentation.adoc#_local_build_instructions[local build
instructions].
. Consult these
xref:improving-the-documentation.adoc#_creating_a_documentation_pull_request[instructions
for creating a documentation PR].
-Note that your `camel-website` will definitely need to be merged possibly
after adjusting the appropriate source URLs back to the camel repositories
rather than any fork repositories used for content PRs.
+Note that your `camel-website` PR will definitely need to be merged after
removing the `source-map` extension configuration used to preview the website
changes.
=== Notes for specific projects
