[DOC] Introducing Quick Start Guide to PL/pgSQL and PL/Python Documentation
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. -- Best regards, Ishaan Adarsh 0001-plpyhton-plpgsql-docu-changes.patch Description: Binary data
Re: [DOC] Introducing Quick Start Guide to PL/pgSQL and PL/Python Documentation
I've addressed the points you raised: 1. *Missing `` Tag:* I reviewed the "Create the Makefile" section, and it seems that 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. 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? -- Best regards, Ishaan Adarsh On Tue, Dec 19, 2023 at 12:28 PM Japin Li wrote: > > 1. > It seems you miss tag in plpgsql "Create the Makefile": > > + > +Create the Makefile > + > + > + Create a Makefile in the pg_plpgsql_ext > directory with the following content: > + > > 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. >
Re: [DOC] Introducing Quick Start Guide to PL/pgSQL and PL/Python Documentation
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. 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. 2. Explanations, code snippets, and examples were included to illustrate key concepts, making it easier for users to follow along. I understand your point about the basics of setting up an extension file structure being repeated. The intention was to provide a self-contained guide within each language's documentation, ensuring that users who directly access a specific language's documentation get a complete guide without having to navigate between sections. If there are areas where the existing documentation is already sufficient or if there are ways to improve the approach, I am open to suggestions. The primary aim is to enhance the accessibility of extension development information for newcomers. -- Best regards, Ishaan Adarsh On Tue, Dec 19, 2023 at 9:18 PM Peter Eisentraut wrote: > 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. >
Re: [DOC] Introducing Quick Start Guide to PL/pgSQL and PL/Python Documentation
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. Best, Ishaan Adarsh On Thu, Dec 21, 2023 at 4:17 PM Pavel Stehule wrote: > Hi > > čt 21. 12. 2023 v 11:18 odesílatel Peter Eisentraut > napsal: > >> 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. >> > > Extensions were designed for C, but they are working with PL well too. > Some of my customers use extensions for PLpgSQL and they are almost happy. > 1) there is nothing else, 2) it is really works > > I agree with Peter - this topic is not what I imagine under "Quick start > guide" > > Regards > > Pavel >
