-
Notifications
You must be signed in to change notification settings - Fork 39
DOC-13056 mobile simplification: p2p pages #956
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
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.
There was a problem hiding this 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
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.
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 |
Sorry to be an absolute pain, but can you redo this based on the DOC-13123 branch, and include the C I have made some pretty big changes to the |
Demangled: * source include:: * :::links * [.column]
There was a problem hiding this 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] |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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
👍
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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 👍)
There was a problem hiding this comment.
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] |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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 🤦)
There was a problem hiding this comment.
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>>. |
There was a problem hiding this comment.
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
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>>. |
There was a problem hiding this comment.
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>> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Overzealous regex
* 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>>. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Overzealous regex
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>>. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Overzealous regex
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
Updated preview which resolves some of these issues. Fix tabshttps://github.com/couchbase/docs-couchbase-lite/blob/antora-assembler-simplification/simplify/attributes.pl#L100-L108 Remove link text from navworks like a dream, good call. ### Overzealous regex Source languageSo we want this interpolated, as it's sometimes used in Still TODO
|
I think I've fixed the |
There was a problem hiding this 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
Woohoo, thanks Simon! |
* 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]>
* 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]>
* 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]>
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:

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.