Description
This plugin enables plugin authors to write their plugin readme content inside a page (or set of pages) or post on their site and then at the click of a button generate the associated valid readme.txt file automatically.
Features
- Simple HTML to Markdown conversion
- Helper widget on Post/Page edit screen to set plugin specific options and Generate the readme
- Global options to set the default values and configure the plugin’s behaviour
- Facility to insert a ‘starter’ template into the current post
- Basic i18n verification and .pot file generation
- Handles single page based readme or page with children
Latest Version – 1.0.2
- Add support for Generation of contextual Help Data Files
- Minor Bug Fixes
Future Updates
Some improvements that I hope to make to the plugin:
- Take content from ‘Visual’ Post/Page edit
- Add popup widget when post displayed showing Header details, and links
Options
The plugin has a number of options some are saved locally with individual posts/pages and some are global and are used to modify the behaviour of the plugin.
Plugin Name
Sets the name of the Plugin for which the readme.txt file is to be generated. This options is saved for each plugin page/post.
Contributors
This sets the list of contributors for the plugin. This option is saved for each plugin page/post, and the default for this value can be set in the global options.
Donate Link
This sets the donate link for the plugin. This option is saved for each plugin page/post, and the default for this value can be set in the global options.
Tags
This sets the list of tags for the plugin. This option is saved for each plugin page/post, and the default for this value can be set in the global options.
Required Version
This sets the minimum required version of WordPress that the plugin will work with. This option is saved for each plugin page/post, and the default for this value can be set in the global options.
Tested Version
This sets the highest version of WordPress that the plugin has been tested against. This option is saved for each plugin page/post, and the default for this value can be set in the global options.
Stable Version
This sets the stable version of the plugin that should be downloaded by users. This option is saved for each plugin page/post.
Readme Location
The plugin subdirectory where the ‘readme.txt’ should be written, usually set to the plugin directory. This is relative to the WordPress plugin directory ‘wp-content/plugins’.
Ignore Sections
If there are any sections or sub-sections that are in the post that should not be present in the readme.txt, then enter their names here as a comma separated list.
Heading Type
This global setting, defines what html element the plugin will use to define the plugin top level headings & sections.
Sub-Heading Type
This global setting, defines what html element the plugin will use to define the plugin sub-headings & sections.
Plugin Category
If all your plugin posts are of a specific category, then put the category’s slug or ID’s in this setting so that the Readme Generator is enabled by default for these posts.
Parent Page
If all your plugin posts are children of a specific post/page, then put the post’s slug or ID’s in this setting so that the Readme Generator is enabled by default for these posts.
Readme Filename
The name of the file that the Readme Generator will create, by default this is ‘readme.txt’, if you want to keep your existing readme.txt set this to something else.
Parse Sub-Pages
If this option is selected then it will also append any pages that are children of the current page to the readme.txt file.
Generate POT
The plugin can generate a .pot file, however this is quiet primitive, enable this option to generate the POT file. This option is saved for each plugin page/post, and the default for this value can be set in the global options.
POT Filename
The name of the .pot file that the Readme Generator will create, by default this is ‘i18n/%SLUG%.pot’. The location is relative to the directory of the ‘readme.txt’, and the phrase %SLUG% will be replaced with the Plugin Name (e.g. plugin-name).
Translations
The plugin comes with translation support but as yet no translations are included. Please refer to the WordPress Codex for more information about activating the translation. If you want to help to translate the plugin to your language, please have a look at the i18n/readme-gen.pot file which contains all definitions and may be used to create a language specific .po file. If you do create a translation please contact me and I will add it to the plugin ready for the next update.
Screenshots
Installation
- Either install directly from your WordPress admin panel, by searching for ‘readme-generator’, or
- Download from the WordPress plugin repository
- Upload and expand the archive into your sites wp-content/plugins directory
- Ensure that all your own plugin directories are writeable by WordPress
- Set the plugin global options.
- For each page/post written for your plugins, set the local settings, then hit the ‘Generate’ button to create the ‘readme.txt’ file.
FAQ
- I’ve tried the plugin and it doesn’t do what I want, help?
-
If you think the plugin doesn’t work, please try contacting me and I will endeavour to help. You can either start a forum topic on the WordPress site or leave a comment on my site on the plugin page Readme Generator Page.
- How is the Content converted into the readme.txt?
-
The plugin by default will copy all the post content into the readme.txt but it tries to convert some HTML markup into ‘readme.txt’ syntax. Roughly it does the following:
- Convert
<h3>Heading</h3>
into== Heading ==
- Convert
<h5>Heading</h5>
into= Heading =
- Convert
<ul><li>Item</li></ul>
into* Item
- Convert
<ol><li>Item</li></ol>
into1. Item
- Convert
Code
into`Code`
- Convert
<a href="LINK">Text</a>
into[Text](LINK)
- Convert
<em>Text</em>
into*Text*
- Convert
<stong>Text</strong>
into**Text**
- Convert
- How is the Plugin header generated?
-
You plugin header is generated using the settings that have been entered into the ‘Generate Readme File’ options box on the page/post that you wish to use as the basis of the readme.txt. These settings are stored with the post/page as metadata, they are saved when you update/create the post.
- Does the plugin generate .pot files automatically?
-
If enabled the plugin will attempt to find all the ‘
__()
‘ and ‘_e()
‘ items in all the php files in the plugin’s directory and generate a standard .pot file using the strings that it finds.
It will provide warnings if it finds more than one text-domain, or if the text domain is missing. However the php file parsing is quiet primitive and unmatched braces or quotes will probably confuse it (‘()”‘). Probably better to use xgettext, if you have it! - Can you show me some examples?
-
The readme file for this plugin was generated using the ‘Readme Generator’ plugin.
The original post can be seen on my site’s plugin page, in your browser select ‘view page source’ to see the HTML that created it (inside the ‘content’ div).
You can see the readme.txt file that was generated by downloading the plugin or directly through this link.
You can see how WordPress renders this readme.txt at the WordPress Plugin repository for the Readme Generator plugin.
Reviews
There are no reviews for this plugin.
Contributors & Developers
“Readme Generator” is open source software. The following people have contributed to this plugin.
ContributorsTranslate “Readme Generator” into your language.
Interested in development?
Browse the code, check out the SVN repository, or subscribe to the development log by RSS.
Changelog
1.0.2
- Add support for Generation of contextual Help Data Files
- Minor Bug Fixes
1.0.1
- Bug Fix – Actually search for selected heading types (h3/h5)
- Add handling of hierarchical set of pages
- Improve handling of list items
Version 1.0
- First version of the plugin