Skip to content

Conversation

osfameron
Copy link
Collaborator

Preview at e.g. https://preview.docs-test.couchbase.com/docs-couchbase-lite-DOC-13056-clean-up-p2p-pages/couchbase-lite/current/android/p2psync-websocket.html

e.g. all the pages under Peer-to-Peer for all mobile SDKs:
image

I've verified with my 👀 that the output for Android pages matches the published output, in terms of structure / images rendering / etc.

Simplification has the following known issues, due to the methodology (using antora assembler as if to generate a single PDF)

  • Some document titles are changed (because assembler uses the left-hand nav as the authoritative source)

  • Some headings are promoted This is actually a "correction" - e.g. the original doc may have had unsemantic headings, with a skipped level. Assembler normalises the output and rewrites headings based on nav level. Though we then remove the correction for nav level, we don't "uncorrect" the fix.

  • Paragraph IDs are namespaced to make them unique. This should be fine within a single document, as assembler should update both anchor and link.
    But deep links from another page may be broken.

  • Code samples are inlined rather than retained as an include:: I've tried to add a // include::... comment in the source so it's easy to fix this.

In addition, you may want to request changes such as:

  • back off from inlining certain {page-...} attributes to retain genericity where actually needed.
    (Probably not here, mostly an issue for e.g. installation pages)

  • Any other demangling I missed.

I've verified with my human eyeballs that the output for Android pages
matches the published output, in terms of structure / images rendering / etc.

Simplification has the following known issues, due to the methodology
(using antora assembler as if to generate a single PDF)

* Some document titles are changed
(because assembler uses the left-hand nav as the authoritative source)

* Some headings are promoted
This is actually a "correction" - e.g. the original doc may have had
unsemantic headings, with a skipped level. Assembler normalises
the output and rewrites headings based on nav level.
Though we then remove the correction for nav level, we don't
"uncorrect" the fix.

* Paragraph IDs are namespaced to make them unique.
This should be *fine* within a single document, as assembler should
update both anchor and link.
But deep links from another page may be broken.

* Code samples are *inlined* rather than retained as an include::
I've tried to add a `// include::...` comment in the source so it's
easy to fix this.

In addition, you may want to request changes such as:

* back off from inlining certain {page-...} attributes to retain
genericity where actually needed.
(Probably not here, mostly an issue for e.g. installation pages)

* Any other demangling I missed.
Copy link
Contributor

@simon-dew simon-dew left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I looked at one page 😄 android/p2psync-websocket.adoc and compared it to the published version. LGTM except that the page title was different? "Peer-to-Peer" in the preview, vs. "Data Sync Peer-to-Peer" in the current version (with "Peer-to-Peer" in the nav). Haven't looked at any other pages.

Haven't approved yet, will probably not approve until 3.2.2 has been published in the next day or two so as not to muddy the waters

@osfameron
Copy link
Collaborator Author

Just to update the PR after our Slack chat:

The issue with titles is mentioned above, and is to do with antora assembler reading the Nav files such as https://github.com/couchbase/docs-couchbase-lite/blob/release/3.2/modules/android/nav-android.adoc?plain=1 and using the nav-specific title.

e.g.

*** xref:android:p2psync-websocket-using-passive.adoc[Passive Peer]

gets labelled "Passive Peer" no matter what the page's title was previously. This obviously makes sense for a PDF export but isn't ideal.

I'll do a manual pass to update the titles 👍

I think the bigger issue ongoing will be with #fragment references for links, which may break some links, and will likely need manual correction as pages are reworked.

@simon-dew
Copy link
Contributor

simon-dew commented Mar 17, 2025

Sorry to be an absolute pain, but can you redo this based on the DOC-13123 branch, and include the C p2psync-websocket.adoc, p2psync-websocket-using-passive.adoc, and p2psync-websocket-using-active.adoc files? (There is no p2psync-custom.adoc for C.)

I have made some pretty big changes to the common-p2psync-websocket.adoc partial, particularly to the Using Secure Storage section.

@simon-dew simon-dew changed the base branch from release/3.2 to DOC-13123 March 18, 2025 15:57
simon-dew and others added 2 commits March 18, 2025 16:08
@osfameron osfameron requested a review from simon-dew March 24, 2025 09:03
Copy link
Contributor

@simon-dew simon-dew left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have a few more changes I'm afraid. I've noted them in a couple of the languages but I think they apply to all of them.

=== Passive Peer

In addition to initializing the database, the Passive Peer must initialize the `MessageEndpointListener`.
The `MessageEndpointListener` acts as a Listener for incoming connections.

// include::android:example$codesnippet_collection.kt[tag=listener,indent=0]
[source]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

None of the source code blocks on the p2p-custom page specify the source language. This is also true in the source material, so it's not a problem with the simplifier. I'm just interested that somehow the current published pages do have a source language. I'm not sure how that's true. Also not saying that the simplifier should somehow add the source code language where not specified; it's something we'll have to do by hand.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aha, it's this line in the _set_page_context_for_‹language›.adoc partial:

:source-language: {param-name}

Is it worth adding that line back in at the start of each page?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I can add it to %keep 👍

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, not sure that helps, I'll look into it

@@ -1,4 +1,4 @@
[#android:p2psync-websocket:::]

= Peer-to-Peer
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The simplifier seems to rename pages using the title from the nav file, rather than the title of the page. Before running the simplifier, can we temporarily remove all link text from the navigation files in order to preserve the original file names? So for example xref:android:p2psync-websocket.adoc[Peer-to-Peer] becomes xref:android:p2psync-websocket.adoc[]. We can reset the nav files afterwards to restore short names in nav.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good call!
I've essentially been making this kind of change in the antora-assembler-simplification branch, but only pulling in changes to the main pages/*.adoc pages in the final PR (e.g. you don't need to worry about it being "temporary" and reverting, it's a build-time fix that we don't need to merge into sources 👍)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(And a much simpler solution that I'd started dreaming up... 🍝 😱 🤓)

=== Using Secure Storage
TLS and its associated keys and certificates might require using secure storage to minimize the chances of a security breach.
The implementation of this storage differs from platform to platform.
This table summarizes the secure storage used to store keys and certificates.

[tabs]
====
[#android:p2psync-websocket:::secure-storage-details-android]
[#secure-storage-details-android]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The tabs aren't showing up in this tabs block. I think it might be because of the anchors. (This is why I reworded the preceding paragraph to say "This table" rather than having a link to Table x.) Can you please remove all the anchors from within this tabs block? I appreciate this might be a job you have to do by hand.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah.. this isn't a tabset in the live docs is it? (Hence why I missed this in visual scan... I'll have compared live rather than your preview 🤦)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like a bug in antora-assembler - the dlists used to mark up tabsets shouldn't be given block anchors, only inline ones 🤦

=== Change Listeners
Use this to monitor changes and to inform on sync progress; this is an optional step.
You can add and a replicator change listener at any point; it will report changes from the point it is registered.

.Best Practice
TIP: Don't forget to save the token so you can remove the listener later

Use the https://docs.couchbase.com/mobile/{major}.{minor}.{maintenance-android}{empty}/couchbase-lite-android/com/couchbase/lite/Replicator.html[Replicator] class to add a change listener as a callback to the Replicator (https://docs.couchbase.com/mobile/{major}.{minor}.{maintenance-android}{empty}/couchbase-lite-android/com/couchbase/lite/AbstractReplicator.html#addChangeListener-java.util.concurrent.Executor-com.couchbase.lite.ReplicatorChangeListener-[addChangeListener()]) -- see: <<android:p2psync-websocket-using-active:::ex-repl-mon>>.
Use the https://docs.couchbase.com/mobile/{major}.{minor}.{maintenance-android}{empty}/couchbase-lite-android/com/couchbase/lite/Replicator.html[Replicator] class to add a change listener as a callback to the Replicator (https://docs.couchbase.com/mobile/{major}.{minor}.{maintenance-android}{empty}/couchbase-lite-android/com/couchbase/lite/AbstractReplicator.html#ex-repl-mon>>.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overzealous regex has chomped up two different links

Suggested change
Use the https://docs.couchbase.com/mobile/{major}.{minor}.{maintenance-android}{empty}/couchbase-lite-android/com/couchbase/lite/Replicator.html[Replicator] class to add a change listener as a callback to the Replicator (https://docs.couchbase.com/mobile/{major}.{minor}.{maintenance-android}{empty}/couchbase-lite-android/com/couchbase/lite/AbstractReplicator.html#ex-repl-mon>>.
Use the https://docs.couchbase.com/mobile/{major}.{minor}.{maintenance-android}{empty}/couchbase-lite-android/com/couchbase/lite/Replicator.html[Replicator] class to add a change listener as a callback to the Replicator (https://docs.couchbase.com/mobile/{major}.{minor}.{maintenance-android}{empty}/couchbase-lite-android/com/couchbase/lite/AbstractReplicator.html#addChangeListener-java.util.concurrent.Executor-com.couchbase.lite.ReplicatorChangeListener-[addChangeListener()]) -- see: <<ex-repl-mon>>.

=== Replicator Status

You can use the
https://docs.couchbase.com/mobile/{major}.{minor}.{maintenance-android}{empty}/couchbase-lite-android/com/couchbase/lite/ReplicatorStatus.html[ReplicatorStatus()] class
to check the replicator status.
That is, whether it is actively transferring data or if it has stopped -- see: <<android:p2psync-websocket-using-active:::ex-repl-mon>>.
That is, whether it is actively transferring data or if it has stopped -- see: <<ex-repl-mon>>.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For some reason this link doesn't work, i.e. it doesn't get replaced with automatic link text and there is no anchor called ex-repl-mon in the output. Could it be because there are two competing lines trying to set the anchor for this example? 688 and 689


The returned _ReplicationStatus_ structure comprises:

* https://docs.couchbase.com/mobile/{major}.{minor}.{maintenance-android}{empty}/couchbase-lite-android/com/couchbase/lite/ReplicatorStatus.html#getActivityLevel()[getActivityLevel()] -- stopped, offline, connecting, idle or busy -- see states described in: <<android:p2psync-websocket-using-active:::tbl-states>>
* https://docs.couchbase.com/mobile/{major}.{minor}.{maintenance-android}{empty}/couchbase-lite-android/com/couchbase/lite/ReplicatorStatus.html#tbl-states>>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overzealous regex

Suggested change
* https://docs.couchbase.com/mobile/{major}.{minor}.{maintenance-android}{empty}/couchbase-lite-android/com/couchbase/lite/ReplicatorStatus.html#tbl-states>>
* https://docs.couchbase.com/mobile/{major}.{minor}.{maintenance-android}{empty}/couchbase-lite-android/com/couchbase/lite/ReplicatorStatus.html#getActivityLevel()[getActivityLevel()] -- stopped, offline, connecting, idle or busy -- see states described in: <<tbl-states>>

== Conflict Resolution

Unless you specify otherwise, Couchbase Lite's default conflict resolution policy is applied -- see xref:android:conflict.adoc[Handling Data Conflicts].

To use a different policy, specify a _conflict resolver_ using https://docs.couchbase.com/mobile/{major}.{minor}.{maintenance-android}{empty}/couchbase-lite-android/com/couchbase/lite/ReplicatorConfiguration.html#setConflictResolver-com.couchbase.lite.ConflictResolver-[conflictResolver] as shown in <<android:p2psync-websocket-using-active:::using-conflict-resolvers>>.
To use a different policy, specify a _conflict resolver_ using https://docs.couchbase.com/mobile/{major}.{minor}.{maintenance-android}{empty}/couchbase-lite-android/com/couchbase/lite/ReplicatorConfiguration.html#using-conflict-resolvers>>.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overzealous regex

Suggested change
To use a different policy, specify a _conflict resolver_ using https://docs.couchbase.com/mobile/{major}.{minor}.{maintenance-android}{empty}/couchbase-lite-android/com/couchbase/lite/ReplicatorConfiguration.html#using-conflict-resolvers>>.
To use a different policy, specify a _conflict resolver_ using https://docs.couchbase.com/mobile/{major}.{minor}.{maintenance-android}{empty}/couchbase-lite-android/com/couchbase/lite/ReplicatorConfiguration.html#setConflictResolver-com.couchbase.lite.ConflictResolver-[conflictResolver] as shown in <<using-conflict-resolvers>>.

== Monitor Listener

Use the Listener's `https://docs.couchbase.com/mobile/{major}.{minor}.{maintenance-android}{empty}/couchbase-lite-android/com/couchbase/lite/URLEndpointListener.html#getStatus--[getStatus]` property/method to get counts of total and active connections -- see: <<android:p2psync-websocket-using-passive:::get-connection-counts>>.
Use the Listener's `https://docs.couchbase.com/mobile/{major}.{minor}.{maintenance-android}{empty}/couchbase-lite-android/com/couchbase/lite/URLEndpointListener.html#get-connection-counts>>.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overzealous regex

Suggested change
Use the Listener's `https://docs.couchbase.com/mobile/{major}.{minor}.{maintenance-android}{empty}/couchbase-lite-android/com/couchbase/lite/URLEndpointListener.html#get-connection-counts>>.
Use the Listener's `https://docs.couchbase.com/mobile/{major}.{minor}.{maintenance-android}{empty}/couchbase-lite-android/com/couchbase/lite/URLEndpointListener.html#getStatus--[getStatus]` property/method to get counts of total and active connections -- see: <<get-connection-counts>>.

from comments by @simon-dew:

* removed incorrect [#id] for dlists within [tabs] set
(bug in antora-assembler)

* make regex for demunging `:::` ids non-greedy

* rename all pages in nav
@osfameron
Copy link
Collaborator Author

osfameron commented Mar 26, 2025

Updated preview which resolves some of these issues.

Fix tabs

https://github.com/couchbase/docs-couchbase-lite/blob/antora-assembler-simplification/simplify/attributes.pl#L100-L108
This checks if we've entered a [tabs] block, and rewrites any [#id] blocks it discovers (UNLESS they have a comma in them, in which case they might be a table macro, and leave them alone... dear God this hacking is getting unsustainably complex, one of the reasons I'd like to get it merged sooner rather than later, before 🤯 means I have to start from scratch.)

Remove link text from nav

works like a dream, good call.
(Has some very minor issues with the top-level pages, and some other bits, which don't crop up for p2p pages)

### Overzealous regex
https://github.com/couchbase/docs-couchbase-lite/blob/antora-assembler-simplification/simplify/attributes.pl#L136
Changes from .* to \S*, e.g. non-whitespace runs.

Source language

So we want this interpolated, as it's sometimes used in [source] macros, but we also want it kept, which means I had to add a NEW case https://github.com/couchbase/docs-couchbase-lite/blob/antora-assembler-simplification/simplify/attributes.pl#L60-L62

Still TODO

  • The <<ex-repl-mon>> issue.

@osfameron
Copy link
Collaborator Author

I think I've fixed the <<ex-repl-mon>> issue with https://github.com/couchbase/docs-couchbase-lite/blob/antora-assembler-simplification/simplify/attributes.pl#L95-L98
but rebuilding preview, and riding off into the night

@osfameron osfameron requested a review from simon-dew March 26, 2025 18:36
Copy link
Contributor

@simon-dew simon-dew left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems to have fixed the issues I noticed. I'm going to say LGTM 👍 let's get this merged into the 3.2.3 feature branch

@osfameron
Copy link
Collaborator Author

Woohoo, thanks Simon!

@osfameron osfameron merged commit 845fd4a into DOC-13123 Mar 27, 2025
1 check passed
@osfameron osfameron deleted the DOC-13056-clean-up-p2p-pages branch March 27, 2025 16:42
simon-dew added a commit that referenced this pull request Mar 28, 2025
* DOC-13056 mobile simplification: p2p pages

I've verified with my human eyeballs that the output for Android pages
matches the published output, in terms of structure / images rendering / etc.

Simplification has the following known issues, due to the methodology
(using antora assembler as if to generate a single PDF)

* Some document titles are changed
(because assembler uses the left-hand nav as the authoritative source)

* Some headings are promoted
This is actually a "correction" - e.g. the original doc may have had
unsemantic headings, with a skipped level. Assembler normalises
the output and rewrites headings based on nav level.
Though we then remove the correction for nav level, we don't
"uncorrect" the fix.

* Paragraph IDs are namespaced to make them unique.
This should be *fine* within a single document, as assembler should
update both anchor and link.
But deep links from another page may be broken.

* Code samples are *inlined* rather than retained as an include::
I've tried to add a `// include::...` comment in the source so it's
easy to fix this.

In addition, you may want to request changes such as:

* back off from inlining certain {page-...} attributes to retain
genericity where actually needed.
(Probably not here, mostly an issue for e.g. installation pages)

* Any other demangling I missed.

* added C docs, and reran based on DOC-13123

* cleanup improvements

Demangled:

 * source include::
 * :::links
 * [.column]

* DOC-13056 iterate

from comments by @simon-dew:

* removed incorrect [#id] for dlists within [tabs] set
(bug in antora-assembler)

* make regex for demunging `:::` ids non-greedy

* rename all pages in nav

* DOC-13056 fix [[ex-repl-mon]] mangling

---------

Co-authored-by: Simon Dew <[email protected]>
simon-dew added a commit that referenced this pull request Apr 29, 2025
* DOC-13056 mobile simplification: p2p pages

I've verified with my human eyeballs that the output for Android pages
matches the published output, in terms of structure / images rendering / etc.

Simplification has the following known issues, due to the methodology
(using antora assembler as if to generate a single PDF)

* Some document titles are changed
(because assembler uses the left-hand nav as the authoritative source)

* Some headings are promoted
This is actually a "correction" - e.g. the original doc may have had
unsemantic headings, with a skipped level. Assembler normalises
the output and rewrites headings based on nav level.
Though we then remove the correction for nav level, we don't
"uncorrect" the fix.

* Paragraph IDs are namespaced to make them unique.
This should be *fine* within a single document, as assembler should
update both anchor and link.
But deep links from another page may be broken.

* Code samples are *inlined* rather than retained as an include::
I've tried to add a `// include::...` comment in the source so it's
easy to fix this.

In addition, you may want to request changes such as:

* back off from inlining certain {page-...} attributes to retain
genericity where actually needed.
(Probably not here, mostly an issue for e.g. installation pages)

* Any other demangling I missed.

* added C docs, and reran based on DOC-13123

* cleanup improvements

Demangled:

 * source include::
 * :::links
 * [.column]

* DOC-13056 iterate

from comments by @simon-dew:

* removed incorrect [#id] for dlists within [tabs] set
(bug in antora-assembler)

* make regex for demunging `:::` ids non-greedy

* rename all pages in nav

* DOC-13056 fix [[ex-repl-mon]] mangling

---------

Co-authored-by: Simon Dew <[email protected]>
simon-dew added a commit that referenced this pull request Apr 30, 2025
* Add peer-to-peer to C nav
* Prepare C peer-to-peer topics
* Format tweaks for peer-to-peer common partial
* Dot unused files
* Embargo unused files which have equivalents in other SDKs
* Add page status label for C peer-to-peer pages
* Page status fix
* DOC-13056 mobile simplification: p2p pages (#956)
* Add URI attributes to avoid double-underscore formatting
* DOC-13133: Reactive UI for Swift (#963)
* Discovery uses platform libraries
* Update API links
* Excessive callouts in configuration summary
* Remove duplicate anchors
* Update Reactive APIs page after PM feedback
* Get rid of "In this section" — subsections are listed in the RH nav
* Remove broken links on Data Sync Peer-to-Peer
* Fix page edition throughout
* Add external callouts for p2preplication example
* Update TLS secure storage
* Update TLS information in C P2P
* CBL-6930: iOS Reactive APIs Snippets (#965)
* Add example snippets to Reactive
* Remove spurious heading from release note partials
* Update release notes for 3.2.3
* Add inline example for p2preplication
* Deprecate URL Endpoint Listener Configuration database field
* Fix C API links post-publication
* Add C API Links for TLS Identity group
* Fix C P2P related links
* CBL-6941 : CBL-C Peer-to-Peer Code Snippet (#967)
* Update C P2P callouts

---------

Co-authored-by: Vlad Velicu <[email protected]>
Co-authored-by: jianminzhao <[email protected]>
Co-authored-by: Pasin Suriyentrakorn <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants