You can contribute to Pods documentation in one of three ways:
-
Adding to our code library.
-
Improving inline documentation for functions or hooks
-
Writing a tutorial.
Don't Worry About All The Details In This Section. We understand some of the details below are a little complex, but we want your contributions and can take care of the details.
The code examples on our documentation site (coming soon) are generated from this repository. You can submit a new code example or propose a change to an existing example by submitting a pull request. Instructions on submitting a pull request via the GitHub web interface, as well as were to put the example are below. You can also clone or fork this repository like any other GitHub repository using the command line or a Git GUI client.
The documentation for all functions, including their definitions parameters, location, and description are automatically generated from the plugin's inline documentation. Any improvements to the inline docs are greatly appreciated and should be submitted to the active development branch of the main Pods GitHub repository and should follow the inline documentation standards for WordPress core development.
More information regarding contributing to inline documentation for hooks, which is our greatest area of need can be found here:
http://pods.io/inline-documentation-filters-actions/
- The current development branch is 3.0-unstable all pull requests should be submit against that branch.
Submission of tutorials, either the full text, or as a link to a post on your own page is encouraged. You are also welcome to submit pull requests to improve or update existing tutorials.
All tutorials, whether they are single post, or a multi-post series must have a file in the tutorial directory. This may be the full text of the tutorial, or an introduction to a multi-post series. If it is a multi-post series, each part should be contained in a subfolder or tutorial with the same name as the parent article.
All posts should include a header with the title, excerpt, author and if it is a part of a multi-part series, the order of the post in the series. The order for multi-part tutorial series is set using the "menu_order" field. This field should be omitted for parent posts. For example:
<script>
{
"title": "SEO For Pods Advanced Content Types",
"excerpt": "Pods Advanced Content Types (ACT) do not work automatically with Yoast's WordPress SEO or any other SEO plugin since they are not WordPress content types. Custom Post Types on the other hand do not share these issues. In this tutorial you will learn search engine optimization for Pods Advanced Content Types, including how to add your ACT to an XML Site Map and generateMeta tags--such as title and description--and Open Graph tags using Pods Pages precode.",
"author": "josh412",
"termSlugs": {
"tutorial_type": [
"advanced","using-pods-pages"
]
},
"customFields": [
{"key":"_yoast_wpseo_title", "value": "Partial Page Caching and Smart Template Parts - Pods Framework"},
{"key":"_yoast_wpseo_metadesc", "value": "Search Engine Optimization (SEO) for Pods Advanced Content Types. Covering: XML Site Maps, Meta tags--such as title and description--and Open Graph tags."}
]
}
</script>
In this example you can see that the primary author of the post is set using Pods.io username. Also, the tutorial is categorized using the "tutorial_type" taxonomy, which only accept certain terms as defined in taxonomies.json. Also SEO title and description are set in the customFields array using the keys "_yoast_wpseo_title" and "_yoast_wpseo_metadesc".
While this may seem complicated, remember that you do not need to be perfect. All submissions will be validated automatically and if needed any errors will be fixed by a member of the Pods team before including. Just like any pull request, we ask that you do your best, but you have the peice of mind of knowing that you can't break anything.
A tutorial post can embed content from anywhere in the code library, for example a code example, or from another GitHub repo, for example the source code of Pods or a Pods plugin. In both cases you use the three ticks, followed by the language method from the markdown language to set syntax highlighting around a @partial() statement.
To embed example code from the Pods Code Library, you would give the full file path, relative to the root of this repository. For example,
```php
@partial(/example/hooks/actions/pods_api_post_save_pod_item_podname/examples/update_taxonomy.php)
```
To embed lines of code from another GitHub repository, you would give the full path to the repository, optionally with line numbers. For example:
```php
@partial(https://github.com/pods-framework/pods/blob/2.x/classes/Pods.php#L261-L275)
```
To add a link to a post on an external site, you will need to create a file in the tutorials, just like with full-text tutorials. The only difference is that you will need to add a "link" field in the header script, with a link to the tutorial. You should also add a few lines about the tutorial in the body of the file, so users will know what the tutorial is about. There is no need to add a link in that text to the article, as the link will be outputted automatically.
Here is an example of a header script for a link post:
<script>
{
"title": "Creating Embedded Video Players From Custom Fields",
"excerpt": "Learn how to take a link to a video directly from a Pods generated custom field and use wp_oembed_get() to display the video in an embedded video player anywhere in your theme.",
"author": "lindsayanng",
"link": "http://webdesignforidiots.net/2014/01/pulling-a-video-from-a-posts-content-and-displaying-it/",
"termSlugs": {
"tutorial_type": [
"adding-custom-fields", "beginner", "media-handling-with-pods",
]
},
"customFields": [
{"key":"_yoast_wpseo_title", "value": "Creating Embedded Video Players From Custom Fields - Pods Framework"},
{"key":"_yoast_wpseo_metadesc", "value": "Learn to use a Pods field and wp_oembed_get() to display an embedded video player anywhere in your WordPress theme."}
]
}
</script>
All code examples should be placed in a sub-directory of the Examples directory. This directory is organized as a mirror of the plugin itself. For examples, code examples for the find method of the Pods class, should go in the examples folder of the find folder, in the Pods folder of the classes folder. This path for this would be: example/classes/Pods/find/examples
Another example, for the save_field method of the PodsAPI class: The example would go in the example folder of the save_field folder in the PodsAPI folder, in the classes folder. The full path would be example/classes/PodsAPI/save_field/examples.
-
Navigate to the correct directory, according to the steps listed above.
-
Click on the file you wish to edit, or add your own by clicking the add file button. If adding a new file, name it for the type of examples(s) you intend to add.
-
Begin the file with opening php tags. Start each example with a multi-line comment using
/**and*/to describe the example. Use single line comments starting with//to explain the code as needed. If appropriate describe output in comments. -
Save the file with a short commit message.
- Submit a pull request against the master branch. If need be elaborate on the code example.
The Pods code library, which is currently under development, is inspired by, and the code that generates the site is forked from the jQuery documentation. For more information see: http://contribute.jquery.org/web-sites. The excellent suggestion to use this approach came from Naomi Bush.
The Pods code library and code reference was created by Dan Stefan Oprean and the Pods Framework team and is generated using this repository as well as: