Migrate doc generation to docbook/fop (postgresql approach)

postgrespro / pgsphere

PgSphere provides spherical data types, functions, operators, and indexing for PostgreSQL.

https://pgsphere.org

BSD 3-Clause "New" or "Revised" License

16 stars 15 forks source link

Migrate doc generation to docbook/fop (postgresql approach) #63

Closed vitcpp closed 9 months ago

vitcpp commented 9 months ago

Dear All,

Please, consider this PR that implements doc generation as postgresql does.

The document generation was redesigned to use the same approach as postgresql does. It uses fop for printable doc generation and xsltproc for html generation. Postgresql stylesheets are used (with some minor changes).

Fixed version propagation when generating the doc. Now, the version is placed in Makefile.common.mk file that is used in doc generation process.

The following make rules were implemented:

make pdf (generates printable doc in A4 and US Letter format)
make pg_sphere-<VERSION>-A4.pdf (generate the printable doc in A4)
make pg_sphere-<VERSION>-US.pdf (generate the printable doc in USLetter)
make html (generates single-page and multi-page html)
make html-singlepage (generate single-page html only)
make html-multipage (generate multi-page html only)

esabol commented 9 months ago

This might be beyond the scope of this PR, but I think it would be a good to have a GitHub Action that generates the HTML documentation whenever there's a change merged/pushed to the master branch and then publishes the generated HTML to GitHub Pages. Something like this:

https://gist.github.com/MichaelCurrin/a698731096f78240f653faf9a9127cba

vitcpp commented 9 months ago

@msdemlei This change is the first step to improve the document generation infrastructure. I propose to cleanup the content after this change because it is a long time work with a lot of PRs, I guess. Thank you for the report. Now I'm concerned - can we synchronize our repos after this change? Is this change suitable for you? If you have some problems with this change, then we have to reconsider the solution.

In this PR I removed the chapters with TBW. I think, it is not a good thing to have empty chapters. We can add such chapters later with some content. I agree, we may create another Issues for that.

vitcpp commented 9 months ago

This might be beyond the scope of this PR, but I think it would be a good to have a GitHub Action that generates the HTML documentation whenever there's a change merged/pushed to the master branch and then publishes the generated HTML to GitHub Pages. Something like this:

@esabol I agree, it is a very good idea! Thank you! I will investigate how to implement it.

esabol commented 9 months ago

Two (different) instances of the minimum supported PostgreSQL version in the documentation:

https://github.com/postgrespro/pgsphere/blob/fb93eb40c8c17f5bbfec66b7578cbbf79277d756/doc/appendixes.sgm#L39

https://github.com/postgrespro/pgsphere/blob/fb93eb40c8c17f5bbfec66b7578cbbf79277d756/doc/install.sgm#L22

These both need to be updated to reflect the current minimum (10.0?). Do you want to do that here in this PR or in a separate PR?

I suppose you could define a variable for this in Makefile.common.mk and populate the value in the documentation in the same fashion as you have with PGSPHERE_VERSION. The only other instance of this minimum supported PostrgeSQL version is in the README.pg_sphere file, I think.

vitcpp commented 9 months ago

Rebased to the latest master.