Jump to content
Kaseem

Documentation - how to contribute

Recommended Posts

I have been using ProcessWire for a while now and I really like to work with it. I am not a big developer but I much appreciate the way it is setup and how the community is supporting it.

Recently I was trying to update a template file and I realised that the function "find" in the core "WireFileTools.php" class was only added rather recently (July 2017) to the 3.1 version of PW.

So I have some questions that maybe someone can try to answer for me:

- is the online documentation in https://processwire.com/api/ref/ intended to reflect only the most recent develop branch or should it include references to additions and changes done to the 3.x? In this case that the function was added only in version 3.x.

- maybe an easier question, how is the API Reference documentation created? Is there a way to contribute on GitHub?

Thanks for your help
Kaseem

 

  • Like 2

Share this post


Link to post
Share on other sites

As far as I know, the documentation gets generated directly from code comments. For example the WireMail class:

API Doc: https://processwire.com/api/ref/wire-mail/

Code: https://github.com/processwire/processwire/blob/master/wire/core/WireMail.php#L9

 

My personal conclusion: if you want to contribute to the docs, you need to understand the "comments markup" and contribute directly to the github code base via issues or pull requests.

 

Edit: and also that you are now a registered forum member for more than one and a half year: Welcome to the forums! :lol:

Edited by horst
added a welcome
  • Like 2
  • Thanks 1

Share this post


Link to post
Share on other sites
4 hours ago, Kaseem said:

Recently I was trying to update a template file and I realised that the function "find" in the core "WireFileTools.php" class was only added rather recently (July 2017) to the 3.1 version of PW.

We do really need @since added to the documentation so module developers can know which methods will require which PW versions, and avoid to confusion when working on older sites. Maybe you could "thumbs up" the existing request and hopefully Ryan will act on it soon: https://github.com/processwire/processwire-requests/issues/158

  • Like 5

Share this post


Link to post
Share on other sites

Thanks to everyone for the very helpful comments and links @horst and @Robin S. The difficulty I see as a newbie is not so much how ProcessWire is working as it is a very straight forward architecture and well documented with examples. My challenge has been to find my way around the forums and the documentation. So far I hesitated asking questions because I don't want to sound too ignorant and overstretch the hospitality of this community. I appreciate all your help very much and I will see how I can really contribute in the future as I think that PW does deserve wider recognition.

  • Like 2

Share this post


Link to post
Share on other sites

Following up on @Robin S suggestion, I have thumbed up the suggestion regarding the @since to the syntax used for the generation of documentation.

I guess technically I can go ahead and suggest a corresponding change to the PW git repository and once @ryan gets around it he can include it if he thinks it is helpful.

Would anyone help me with another question flowing from the above? How can I find the PW version in the file history on github? I have found the change when the function "find" was added to "wire/core/WireFileTools.php" 

https://github.com/processwire/processwire/commit/786995f85e3664615fe2cc5ff269f4bd59b6a7f2#diff-fd4a44895145a0f0ea6d437d7e7b62c0    

Where can I find the PW version under which this commit was later released?

  • Like 1

Share this post


Link to post
Share on other sites
30 minutes ago, Kaseem said:

Where can I find the PW version under which this commit was later released?

Finding out the manual way....

browse-repo-from-point.thumb.gif.04bc5c68e6394b36c0a73459b0feab9a.gif

Welcome to the forums @Kaseem

  • Like 3
  • Thanks 1

Share this post


Link to post
Share on other sites

Thank you @kongondo for this very useful tutorial. The version when find() was added seems to be 3.0.66.

I have now created a pull request with the version info of when the functions find() and includeOnce() were added using the @since syntax suggested by @Robin S 

  • Like 2

Share this post


Link to post
Share on other sites

So if any documentation project aimed at creating a user/admin/modules/best practices manual(s) was started up, I would be happy to help however I could.  I'm more of a back-end server person, not a web designer, and I really don't understand how to effectively use pw yet so maybe I could learn something from writing stuff.

  • Like 3

Share this post


Link to post
Share on other sites

Thanks @Doug G for your offer. I see myself a bit in the same situation. Maybe it is helpful to summarise here the documentation as it is available on the PW website and then ask for contributions to this list as to get a full picture of what already exists and what is actually still missing.

PW Documentation

  • API Reference : Gives an overview of the API variables and detailed information about the class functionality. According to @horst 's post this is directly generated from the code based on a special markup code included in the PHP comments.
  • Tutorials : As the name suggests, giving insights into a number of topics. How to contribute to the tutorial?
  • API Cheatsheet : A comprehensive reference of ProcessWire API variables, methods and properties – all on one page. Is this also directly generated from the code? 
  • API Documentation : Learn more about the API including the concepts behind it, how to work with template files, and how to develop modules. Also labeled as: DEVELOPING A SITE IN PROCESSWIRE. Covers additionally topics like Concept, Template Files, Selectors, Include&Bootstrap, Syntax, Hooks, Plugin Modules, Users&Access, Arrays, Fieldtypes, Multi-Language Support and Coding Style Guide. How to contribute to this documentation?
  • Directory Structure : This section outlines ProcessWire’s default directory structure, highlighting the locations where your site’s files go.
  • Template Files : Every time a page is loaded on your site, ProcessWire looks at what template is assigned to the page, loads it, gives it several API variables, and then runs it as a PHP script. This section covers the use of template files and serves as an introduction to using ProcessWire’s API with examples. This can be accessed also by way of "API Documentation"
  • Selectors : A selector allows you to specify fields for finding a page or group of pages that match your criteria. Selectors in ProcessWire are loosely based around the idea and syntax of attribute selectors in jQuery. This can be accessed also by way of "API Documentation"
  • Multi-Language Support : ProcessWire makes multi-language support easy with multi-language fields, URLs (page names) and code internationalization.

  • Security : Security is our number one priority with ProcessWire. Make it your number one priority too. In this section we attempt to cover some of the more important aspects in maintaining a secure installation.

  • Install & Upgrade : Covers installation of ProcessWire, troubleshooting and upgrades.

Is there more documentation hidden on this site? Or on different sites?

  • Like 4

Share this post


Link to post
Share on other sites
8 hours ago, Kaseem said:

According to @horst 's post this is directly generated from the code based on a special markup code included in the PHP comments.

More on this:

8 hours ago, Kaseem said:

How to contribute to the tutorial?

Write one then send a pm to Ryan :) 

8 hours ago, Kaseem said:

Is this also directly generated from the code? 

Probably, see:

https://processwire.com/blog/posts/processwire-3.0.60-core-updates-and-more/ "...With the API reference now up-to-date, we'll soon be looking at the cheatsheet and hopefully updating that to pull data from the API Explorer module as well."

Also search for the word cheatsheet in these:

8 hours ago, Kaseem said:

How to contribute to this documentation?

Same as the tutorials ;)

8 hours ago, Kaseem said:

Is there more documentation hidden on this site? Or on different sites?

Yes, there is. It's too late here for me to compile a good list but I will try to do it in the following days if others do not provide something faster than me...

  • Like 1
  • Thanks 1

Share this post


Link to post
Share on other sites

I am compiling this list and the contributions of @szabesz - thanks a lot.

To make contributions to the documentation based on the code, it seems best to contribute to the code on https://github.com/processwire/processwire and send a pull request to @ryan

To make contributions to the rest of the documentation, it seems best to send them to @ryan for example by pm.

PW Documentation

  • API Reference : Gives an overview of the API variables and detailed information about the class functionality. This is directly generated from the source code  (see API Explorer module) based on a special markup code included in the PHP comments.
  • Tutorials : As the name suggests, giving insights into a number of topics.
  • API Cheatsheet : A comprehensive reference of ProcessWire API variables, methods and properties – all on one page. The intention is to pull this information also directly from the code using the API Explorer module (see this post - What about the cheatsheetis this actually implemented by now?) 
  • API Documentation : Learn more about the API including the concepts behind it, how to work with template files, and how to develop modules. Also labeled as: DEVELOPING A SITE IN PROCESSWIRE. Covers additionally topics like Concept, Template Files, Selectors, Include&Bootstrap, Syntax, Hooks, Plugin Modules, Users&Access, Arrays, Fieldtypes, Multi-Language Support and Coding Style Guide.
  • Directory Structure : This section outlines ProcessWire’s default directory structure, highlighting the locations where your site’s files go.
  • Template Files : Every time a page is loaded on your site, ProcessWire looks at what template is assigned to the page, loads it, gives it several API variables, and then runs it as a PHP script. This section covers the use of template files and serves as an introduction to using ProcessWire’s API with examples. This can be accessed also by way of "API Documentation"
  • Selectors : A selector allows you to specify fields for finding a page or group of pages that match your criteria. Selectors in ProcessWire are loosely based around the idea and syntax of attribute selectors in jQuery. This can be accessed also by way of "API Documentation"
  • Multi-Language Support : ProcessWire makes multi-language support easy with multi-language fields, URLs (page names) and code internationalization.

  • Security : Security is our number one priority with ProcessWire. Make it your number one priority too. In this section we attempt to cover some of the more important aspects in maintaining a secure installation.

  • Install & Upgrade : Covers installation of ProcessWire, troubleshooting and upgrades.

More on how different ways how documentation is generated or updated in these posts:

  • Like 2

Share this post


Link to post
Share on other sites

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

Guest
Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.


  • Recently Browsing   0 members

    No registered users viewing this page.

×
×
  • Create New...