Update documentation

[carstingaxion]

Is your enhancement related to a problem? Please describe.

I’d like to enhance the existing documentation. The current README.md houses one part of dev docs, that is going to be moved into the /docs/developer folder with #653 ✅

It might help contributors and extenders as well to have some additional docs about:

docs/developer/

Understanding GatherPress

• https://github.com/GatherPress/gatherpress-alpha
• close-to-core philosophy & community promise
• wpcli commands that GatherPress provides
• Filters & Actions available in the plugin
  • Autoloader
  • Settings API
  • Import & export
• Implementation-Details on registered …
  • post types
  • post meta data
  • taxonomies
  • user meta data
  • settings
  • REST endpoints
• URLs & permalinks (URLs of the plugin #744)
• custom DB table
• Multisite compatibility

Extending GatherPress

• Demo-data and prepared WordPress playgrounds
• Import & Export events, venues & topics
• https://github.com/GatherPress/gatherpress-awesome
• Blocks
  • hookable patterns (Prepare for new block variations 1/3: hookable-patterns, slot-fills & docs #888)
  • Add or Remove blocks from the default event & venue templates using the Block Hooks API (blocks in the big picture #626)
  • Editor slots available (Prepare for new block variations 1/3: hookable-patterns, slot-fills & docs #888)
  • Styling event- & venue-blocks with theme.json
• post-processing RSVPs (Add docs about action hooks when someone do the RSVP #787 (comment))
• Overwrite templates from within a theme (DO NOT MERGE | new calendar endpoints #831)
• Add custom URL endpoints (DO NOT MERGE | new calendar endpoints #831)
• Add custom settings to GatherPress‘ settings tabs

docs/contributor/

• Code of conduct
• Collaborator Access
• code contribution
  • wp-env development environment (existing)
  • tools & workflows for quality standards
    • screenshots for w.org (Migrate screenshot generator workflow to use wp-playground/cli #822)
    • Version bump script by @mauteri
    • contributor- & credits script by @mauteri
    • e2e tests (NEW e2e environment using playground cli #810)
    • unit tests (DO NOT MERGE | new calendar endpoints #831)
    • Prepare & publish a release
  • forking & git branch management (Add branching model to dev docs #948)
• no-code contribution
  • Test actual PRs (Update to readme.md (change to video link and deletion of duplicate paragraphs) #805 (comment))
  • Add your events to the demo-data (https://github.com/GatherPress/demo-data)
  • Translate the plugin
  • Join the weekly huddle & the slack channel
  • Help Triaging tickets
  • Spread the word in social media & blog about GatherPress
  • Take part in the pilot program and run your meetup with demo.gatherpress.org
• …

docs/user/

• Install
• Settings
• Create a new event
• Create a new venue
• Event topics
• Send Emails (https://gatherpress.slack.com/archives/CNZS6PPFZ/p1725504169802479?thread_ts=1725386505.050289&channel=CNZS6PPFZ&message_ts=1725504169.802479)
• Export to and subscribe with your calendar app (DO NOT MERGE | new calendar endpoints #831)
• Blocks overview
  • Event Query block
  • Event Date block
  • …

Designs

For now, I recommend, creating static markdown files until a new Playground-powered documentation workflow #765 is ready. A structure with named folders and just one README.md file per directory seems to be the most common way to do that.

The written docs should be accompanied by an auto-generated code reference.

Staying with GatherPress‘ close-to-core philosophy, I’d like to re-use existing stuff and get the benefit of a well-known UI on top. A working PoC for a GatherPress code reference using the same theme as developer.wordpress.org, can be found here carstingaxion/gatherpress-devhub#1 (comment)

Describe alternatives you've considered

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

[carstingaxion]

He @shawfactor, what have you been searching for recently (in the context of GatherPress)? What needs to be in the dev-docs from your extenders-point-of-view? I would really appreciate your feedback over here!

[carstingaxion]

May I invite you too @oscarhugopaz, as you seem to do more development work, than a typical user, would you please add your thoughts here?!

What needs to be part of GatherPress developer documentation?

[shawfactor]

I’ve never looked at the documentation but I managed to understand the code. My only only bugbear was that many methods are protected which are useful for building templates and other plugin extensions. I’ve raised an issue for this already though as there are no security reasons why these methods are not accessible to everyone

[carstingaxion]

I’ve never looked at the documentation but I managed to understand the code.

Thanks @shawfactor, in the name of all who wrote that understandable code!

I felt & feel the same, that’s why I really enjoy contributing to that project! The existing code base is understandable and makes a lot of sense.

Maybe we could keep your statement for a later, as a first testimonial. Accompanying your great review on w.org ;)

My only only bugbear was that many methods are protected which are useful for building templates and other plugin extensions. I’ve raised an issue for this already though as there are no security reasons why these methods are not accessible to everyone

We talked about your issue #635 in last weeks huddle and concluded that the current implementation is based more on a general design decision, rather than being planned for extension. But we agree and are willing to change some of the methods.

Be absolutely invited to open PRs for all changes you see a need for!

[shawfactor]

Completely agree with you. I swapped my sites over from another events calendar as gatgerpress does things in a true open source way, seems open to suggestions, and plans to work with existing Wordpress plugins Happy for you to use my words as a testimonial I believe having accessible methods or some alternatives like template functions is essential though. Buddypress, bbpress, woocommerce etc don’t try to do everything. Instead they benefit from an ecosystem that has grown with them. In order to achieve this, accessing event characteristics like times and descriptions in a flexible way (without having to reinvent the wheel) is essential. Pere

…

On Wed, 21 Aug 2024 at 10:32 PM, Carsten Bach ***@***.***> wrote: I’ve never looked at the documentation but I managed to understand the code. Thanks @shawfactor <https://github.com/shawfactor>, in the name of all who wrote that understandable code! I felt & feel the same, that’s why I really enjoy contributing to that project! The existing code base is understandable and makes a lot of sense. Maybe we could keep your statement for a later, as a first testimonial. Accompanying your great review on w.org ;) My only only bugbear was that many methods are protected which are useful for building templates and other plugin extensions. I’ve raised an issue for this already though as there are no security reasons why these methods are not accessible to everyone We talked about your issue #635 <#635> in last weeks huddle and concluded that the current implementation is based more on a general design decision, rather than being planned for extension. But we agree and are willing to change some of the methods. Be absolutely invited to open PRs for all changes you see a need for! — Reply to this email directly, view it on GitHub <#656 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAE55YPC2M7GILHUC7AA3STZSSCE7AVCNFSM6AAAAABHHFNRYCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGMBRHE2DANBUHE> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[carstingaxion]

The index of docs/contributor could become also the Contribution Guidelines GitHub wants us to add.

[MervinHernandez]

QUEUE for Discussion - October 25

• Mervin - strongly suggests breaking up this documentation ticket into smaller tickets for delegating / better tracking.
  -- Split 1 - section "x" of documentation
  -- Split 2 - connecting our dev docs to git required "Contributor Guidelines"
• ?? Should this be split into a ticket for (more) changing of protected methods?

[MervinHernandez]

Queued to break this apart.

[MervinHernandez]

Queued to break this apart.