Thread: [DOC] Introducing Quick Start Guide to PL/pgSQL and PL/Python Documentation

I have made some documentation enhancements for PL/pgSQL and PL/Python sections. The changes include the addition of a Quick Start Guide to facilitate a smoother onboarding experience for users.

On Sat, 16 Dec 2023 at 18:49, Ishaan Adarsh <ishaanad9@gmail.com> wrote:
> Hi
>
> I have made some documentation enhancements for PL/pgSQL and PL/Python
> sections. The changes include the addition of a Quick Start Guide to
> facilitate a smoother onboarding experience for users.
>
> Patch File Name:
> 0001-plpyhton-plpgsql-docu-changes.patch
>
> Patch Description:
> This patch introduces a Quick Start Guide to the documentation for PL/pgSQL
> and PL/Python. The Quick Start Guide provides users with a step-by-step
> walkthrough of setting up and using these procedural languages. The goal is
> to improve user accessibility and streamline the learning process.
>
> Changes Made:
> 1. Added a new section titled "Quick Start Guide" to both PL/pgSQL and
> PL/Python documentation.
> 2. Included step-by-step instructions for users to get started with these
> procedural languages.
> 3. Provided explanations, code snippets, and examples to illustrate key
> concepts.
>
> Discussion Points:
> I am seeking your feedback on the following aspects:
> - Clarity and completeness of the Quick Start Guide
> - Any additional information or examples that could enhance the guide
> - Suggestions for improving the overall documentation structure
>
> Your insights and suggestions are highly valuable, and I appreciate your
> time in reviewing this documentation enhancement.

1.
It seems you miss <filename> tag in plpgsql "Create the Makefile":

+  <sect2 id="plpgsql-step4">
+    <title>Create the Makefile</title>
+
+    <para>
+      Create a Makefile in the <filename>pg_plpgsql_ext</filename> directory with the following content:
+    </para>

2.
We expected use CREATE EXTENSION to load the extension, should we add the
following in extension--version.sql?

-- complain if script is sourced in psql, rather than via CREATE EXTENSION
\echo Use "CREATE EXTENSION pair" to load this file. \quit

--
Regrads,
Japin Li
ChengDu WenWu Information Technology Co., Ltd.

On Tue, 19 Dec 2023 at 17:57, Ishaan Adarsh <ishaanad9@gmail.com> wrote:
> I've addressed the points you raised:
>
> 1. *Missing `<filename>` Tag:*
> I reviewed the "Create the Makefile" section, and it seems that <filename>
> tags are appropriately used for filenames. If there's a specific instance
> where you observed a missing tag, please provide more details, and I'll
> ensure it's addressed.
>

Thanks.

> 2. *Use `CREATE EXTENSION` in "extension--version.sql":*
>  Considering that there's already a CREATE EXTENSION step in the quick
> start guide, I can include a note in the general documentation to explain
> the rationale without repeating it in the individual script. What do you
> think?

Agreed.

--
Regrads,
Japin Li
ChengDu WenWu Information Technology Co., Ltd.

On 16.12.23 11:49, Ishaan Adarsh wrote:
> 1. Added a new section titled "Quick Start Guide" to both PL/pgSQL and 
> PL/Python documentation.
> 2. Included step-by-step instructions for users to get started with 
> these procedural languages.
> 3. Provided explanations, code snippets, and examples to illustrate key 
> concepts.

The way I read it, that's not really what your patch does.  Your patch 
explains how to write an extension in PL/pgSQL and PL/Python, 
respectively.  Which is okay, I guess, but a bit unusual.  But I 
wouldn't call that an unqualified "quick start" in the respective 
languages.  Also, it seems to repeat the very basics of setting up an 
extension file structure etc. repeatedly in each chapter.

The existing documentation has "explanations, code snippets, and 
examples".  Are they not good?  Do you have more?  Better ones?  Why are 
yours separate from the existing ones?

I think it would be useful to take a step back here and define the 
purpose of a bit clearer.

On 19.12.23 17:26, Ishaan Adarsh wrote:
> Subject: Clarification on the Purpose of the Patch
> 
> Hi Peter,
> 
> The intention was to address the challenge faced by newcomers in 
> understanding how to write an extension for PostgreSQL. The existing 
> documentation, while comprehensive, lacks a consolidated and 
> easy-to-follow tutorial that serves as a quick start guide. The goal was 
> to create a beginner-friendly resource that assumes only knowledge of 
> Postgres and the target language, making it accessible for new 
> contributors because the barrier for entry is prohibitive for new 
> contributors. There are various third-party blog posts focusing on 
> different areas, and sometimes contradictory.

Have you seen this: 
https://www.postgresql.org/docs/devel/extend-extensions.html#EXTEND-EXTENSIONS-EXAMPLE

Maybe that could be extended/modified/simplified?

> Specifically:
> 1. The new section titled "Quick Start Guide" aims to provide 
> step-by-step instructions for users to get started with writing 
> extensions in PL/pgSQL and PL/Python.

What's confusing here is writing an extension in a PL language is not a 
normal use case I'd say.  The normal use case involves some C code.

On Thu, 21 Dec 2023 at 21:03, Pavel Stehule <pavel.stehule@gmail.com> wrote:
> Hi
>
> čt 21. 12. 2023 v 13:37 odesílatel Ishaan Adarsh <ishaanad9@gmail.com>
> napsal:
>
>> The recent documentation patches are part of my GSoC 2023 project
>> <https://wiki.postgresql.org/wiki/GSoC_2023#Postgres_extension_tutorial_.2F_quick_start>
>> to develop a comprehensive PostgreSQL extension development tutorial, it
>> assumes only a basic knowledge of Postgres and the target programming
>> language.
>>
>> The entire project is available on GitHub: Postgres-extension-tutorial
>> <https://github.com/IshaanAdarsh/Postgres-extension-tutorial/blob/main/SGML/intro_and_toc.md>.
>> It covers many topics, including prerequisites, writing extensions,
>> creating Makefiles, using procedural languages, incorporating external
>> languages, writing regression tests, and managing extension releases. *The patch submitted
>> for procedural languages, specifically PL/pgSQL and PL/Python, is part of
>> the procedural language section within the broader tutorial. *
>>
>> Based on the feedback I think there is a real need
>> <https://twitter.com/jer_s/status/1699071450915938609> for this as this
>> is a very important and growing part of the Postgres ecosystem. Currently,
>> all the extension material is scattered and very limited. There are
>> various third-party blog posts focusing on different areas, and sometimes
>> contradictory. The main motivation behind making this is to make the barrier
>> for entry less prohibitive for new contributors.
>>
>> I would greatly appreciate your input on how to add it to the existing
>> documentation (this is where I have major doubts) and any suggestions on
>> how to proceed. If there are areas where the existing documentation is
>> already sufficient or if there are ways to improve the overall structure, I
>> am open to making adjustments.
>>
>
> https://www.postgresql.org/docs/current/plpgsql-development-tips.html and
> new section - deployment or packaging to extensions
>
> I agree so https://www.postgresql.org/docs/current/plpgsql-overview.html is
> under dimensioned, but packaging should not be there
>

It seems redundant if we add this for each PL, maybe a separate section to
describe how to package PL into extensions is better.

--
Regrads,
Japin Li
ChengDu WenWu Information Technology Co., Ltd.

On Fri, Dec 22, 2023 at 12:04 PM Pavel Stehule <pavel.stehule@gmail.com> wrote:
> I have not a strong opinion about it. My personal experience is so 99% PL code is PLpgSQL, so it can be there, and
otherPL can be referenced there. I am not sure if there is some common part for all PL. 

After reading over this thread, it seems clear to me that there is no
consensus to proceed with this patch in its current form, and the
discussion seems to have stalled. Accordingly, I've marked this
"Returned with Feedback" in the CommitFest.

Ishaan, if you plan to rework this into a form which might be
acceptable given the review comments made up until now, please feel
free to change this back to "Waiting on Author", and/or move it to a
future CommitFest.

--
Robert Haas
EDB: http://www.enterprisedb.com