[PGSQL] Antora documentation

[chibenwa]

DOD: we have a full Antora documentation dedicated to the PG server just like distributed server.

we should limit copy and paste to the maximum. We should use Partial to the maximum.

Likely we should move the Antora doc of the distributed server back into /docs to ease this.

We will do that after the branch is merged with master to ease this.

[Arsnael]

Summer topic, but let's start thinking about it

[quantranhong1999]

we should limit copy and paste to the maximum. We should use Partial to the maximum. Likely we should move the Antora doc of the distributed server back into /docs to ease this.

I see a lot of docs are common between distributed-app and postgres-app.

Are you suggesting we only write the docs needed for postgres-app for now, and wait for the postgresql branch got merged into master then refactor the Antora docs to be reused for both distributed-app and postgres-app?

[Arsnael]

I see a lot of docs are common between distributed-app and postgres-app.

Are you suggesting we only write the docs needed for postgres-app for now, and wait for the postgresql branch got merged into master then refactor the Antora docs to be reused for both distributed-app and postgres-app?

The goal is to have those common parts as partials I think.

Waiting for postgres to be merged to the main branch could be a thing. But can we expect the community to adopt postgres app without proper doc part of it as well? I ain't sure.

An other way would be to move back distributed doc to root doc in master branch, rebase postgres on master, and then propose the necessary changes on postgres branch for postgres doc?

[quantranhong1999]

An other way would be to move back distributed doc to root doc in master branch, rebase postgres on master, and then propose the necessary changes on postgres branch for postgres doc?

Sounds good to me.

[Arsnael]

Didn't have too much time to look deeper in this, but quickly:

• upgrade antora version? (latest is 3.1, doc still refers to 2.3)
• migrate back distributed doc to antora doc root folder
• identify all common parts between postgres and distributed (S3, search indexation, rabbitmq, ...) and move them into partials with distributed
• write the rest of the postgres specific doc in its own section

Needs a deeper look on which parts are common

[Arsnael]

What I can think of when looking at the distributed documentation:

• Architecture: Storage is pg specific I think (slightly different) but other sections can partial

  • Implemented standards => partials
  • Consistency model => Opensearch and RabbitMQ consistency model can be partials
  • Specialized instances => partials (bit of rewording needed?)

• Run

  • Run with Java / Docker: Could be partials (warning lots of distributed terms)
  • Run with K8S: no K8S contributions for pg-app in James (should we?)

• Configuration => links are different, but rest same. partials?

  • Protocls => partials
  • Storage dependencies: => blobstore.properties => except cassandra parts, can partial the rest => opensearch, rabbitmq, redis, tika.properties => partials
  • Core components => partials
  • Extensions => partials

• Operate

  • Operator guide => can partial except Solving cassandra inconsistencies, Setting Cassandra user permissions, Cassandra table level configuration and Updating Cassandra schema version sections
  • Performance checklist => can partial except Database setup and Cassandra section
  • Logging => partials
  • webadmin => partials except some cassandra specific sections and be careful of healthcheck too, some components differ
  • Metrics => partials
  • Migrating existing data => partials
  • Command Line Interface => partials
  • Security checklist => partials

• Extending server behavior => can be fully partials

• Performance benchmark => partials

  • Database benchmarks => need to be pg specific
  • James benchmark => partials

Note: can use attributes in partial pages to customize some terms. For example there is a lot of Distributed James server mentions, that could be replaced by an attribute which would allow to replace those mentions by Postgres James Server for example. Need to see how far we are willing to use those attributes. For example Configuration page, would be very similar for postgres for most of the page, just the links to conf sample files would be mainly different. Would it make sense to use attributes? Or would it make it too complex cause too many for this case?

[vttranlina]

Note: how to use variable (not sure if it is called "variable" or not, somewhere in Antora document write it is "attribute" )

Eg:

The All.adoc

=== All

The docker container image is {jamesImageName}

Using variable for pass dynamic value

:jamesImageName: james-cassandra
include::partial$All.adoc[]

:jamesImageName: james-postgres
include::partial$All.adoc[]

Then the document is generated:

I tried the another way (as Antora write it) but it does not work

include::partial$All.adoc[jamesImageName,james-postgres] // not work
include::partial$All.adoc[jamesImageName=james-postgres] // not work 
include::partial$All.adoc["jamesImageName"="james-postgres"] // not work

[vttranlina]

Would it make sense to use attributes? Or would it make it too complex cause too many for this case?

Right now, I think it's fine. eg when running with Java/Docker, the process is quite similar between distributed Cassandra and Postgres. We simply need to change the image or JAR names, and we'll have a new adaptable document.

[Arsnael]

@vttranlina the way you used redefining the attribute value before including the partial in the page is the way, form what I found.

Would like to add though that you can define a default value for the attribute on top of the partial page as well. Thus we could think of having distributed version values as default (no need to override them before including partials in distributed pages) then only override for postgres

[Arsnael]

List of tasks I am thinking of:

• upgrade antora version
• migrate back distributed doc to antora doc root folder
• set up Postgresql antora documentation with the main page
• Objectives and motivation page for postgres
• PG Architecture section
• PG run section
• PG Configuration section
• PG Operate section
• PG Extending server behavior section
• PG Performance benchmark section

Do we need extra sections btw that are exclusive to postgres doc?