Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

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

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 ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Merged
vitcpp merged 6 commits intopostgrespro:masterfromvitcpp:doc-improve-1
Sep 18, 2023

Conversation

vitcpp
Copy link
Contributor

@vitcppvitcpp commentedSep 13, 2023•
edited
Loading

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)

@vitcppvitcppforce-pushed thedoc-improve-1 branch 2 times, most recently from48a30ee to0ea8381CompareSeptember 14, 2023 09:36
@vitcppvitcpp mentioned this pull requestSep 14, 2023
Copy link
Contributor

@msdemleimsdemlei left a comment

Choose a reason for hiding this comment

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

Thanks for tackling this infrastructure task!

I'm not familiar enough with postgres doc practices to have an informed opinion about every line in the change, but I've built the PDFs and the multipage HTML, which both looks good.

I also don't know what to write instead of the tbw-s. Perhaps we should create an issue for them?

Finally, I'm not sure if we want to smuggle such a change in here, but since I ran into it during review: sect. 2.2 says "You will need PostgreSQL 9.1 or above." almost certainly is wrong these days. Perhaps we can say "The minimal postgres version for any given pgsphere version can be found at xy" (where I'm not sure what "xy" would be at this point)? Or just drop the sentence entirely on grounds that it will probably always under-updated and no information is better than wrong information?

@esabol
Copy link
Contributor

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
Copy link
ContributorAuthor

@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
Copy link
ContributorAuthor

vitcpp commentedSep 15, 2023•
edited
Loading

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 reacted with thumbs up emoji

@esabol
Copy link
Contributor

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

Compatibility with <application>PostgreSQL</application> 9.2

9.1</application> or above. We assume that you have

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 inMakefile.common.mk and populate the value in the documentation in the same fashion as you have withPGSPHERE_VERSION. The only other instance of this minimum supported PostrgeSQL version is in theREADME.pg_sphere file, I think.

The document generation was redesigned to use the same approach as postgresqldoes. It uses fop for printable doc generation and xsltproc for htmlgeneration. Postgresql stylesheets are used (with some minor changes).Fixed version propagation when generating the doc. Now, the version isplaced in Makefile.common.mk file that is used in doc generationprocess.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)
Remove inclusion of 'pg_config --pgxs' makefile because it is notrequired to create the documentation. This makefile was designed to beincluded in top-level extension makefile. Inclusion in the doc/Makefileresults into some unexpected behaviour when using 'install' or 'all' rules.Remove gmake -C doc install in .travis.yml because this target didn'tdo anything. I guess that the installation of the manual should beimplemented in the top-level extension Makefile file, not in thedoc/Makefile.
@vitcpp
Copy link
ContributorAuthor

Rebased to the latest master.

esabol reacted with thumbs up emoji

@vitcppvitcpp merged commit3a912fc intopostgrespro:masterSep 18, 2023
Sign up for freeto join this conversation on GitHub. Already have an account?Sign in to comment
Reviewers

@msdemleimsdemleimsdemlei approved these changes

@esabolesabolesabol approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

3 participants
@vitcpp@esabol@msdemlei
[8]ページ先頭
©2009-2025 Movatter.jp