kongondo

ProcessWire ApiGen (dynamic + up to date + all branches)

Recommended Posts

Finally, I got spared some time to work on a project I have been meaning to do for a while. This follows on from this request and other discussions about the pros/cons of an ApiGen for ProcessWire. I am all for such docs as long as two conditions are met: (i) That it is clearly indicated who the target audience is; and (ii) that the docs are regularly updated. I think this project meets both.
 
I have created a GitHub project and project pages for hosting regularly auto-updated PHP ApiGen Docs for ProcessWire 3 (master and dev) as well as ProcessWire 2.8 (master). We also have ProcessWire 2.7 (master and dev) docs but these are not updated since this version of ProcessWire is no longer active.

The whole doc-generation process is automated including auto-pushing changes to GitHub. The current cycle is:

  • ProcessWire 2.8.x Master branch docs: updated once at the beginning of every month
  • ProcessWire 3.x Master branch: updated once at the beginning of every month
  • ProcessWire 3.x Dev branch: updated once weekly, every Friday

Docs are generated for all .php and .module files under /wire/core/ and /wire/modules/.
 
Currently, this is all done via my home PC. I am on a Windows machine so nothing could really go wrong... :P  ;) . Barring the unforeseen, these docs should be roughly in step with the latest ProcessWire commits. Now running on a remote server.
 
Tools used

  • Windows PowerShell (move over wget!  :P ) wget
  • Git-Bash
  • Windows Task Scheduler (there's your cron right there  :lol: )  cron
  • Pear APIGEN
  • Scripts: PowerShell, Bash Script, VBS and Batch files
  • A couple of stress balls

I hacked together a dark theme for this project, sublime-text default look. The CSS still needs some work, all help appreciated, thanks. If anyone would like to create an alternative theme, we could incorporate a theme switcher.
 
Feeback, thoughts, suggestions (e.g. text in READMe, etc)? 
 
Credits to Ryan for writing such well-commented code...otherwise this project would not have been possible.
 
From the READMe
 

Quote

Important
Please note that these are technical documentation not aimed at the average ProcessWire user but developers who are curious or need to find out in more detail about a specific ProcessWire class or function and/or use this as a reference. Most of the technical stuff here steps outside ProcessWire's public API into the inner workings of the CMF/CMS. If you would like to know more about such stuff, then this is for you. For all other uses, please use the regular ProcessWire API docs and the ProcessWire Cheatsheet.

  • Like 23

Share this post


Link to post
Share on other sites

Feeback, thoughts, suggestions (e.g. text in READMe, etc)?

Thanks for setting this up. While it's important to note that methods and such found via this are not necessarily intended as public API, and may be subject to change in later versions, I think it provides a good middle ground between pure code and manually edited docs  :)

Since you wanted feedback, one point I'd like to mention is the theme. This is partly opinion-based thing, but I find the light color scheme of the earlier apigen thing more readable. In the dark theme especially the dark lines tend to disappear, and some of the colors (such as the red headers) kind of make my eyes ache.

  • Like 2

Share this post


Link to post
Share on other sites

A "Like" isn't enough :)

Great work and a big step to an (automated) up to date PW documentation!

A light color schema would be better. As teppo said.

  • Like 1

Share this post


Link to post
Share on other sites

Thanks for setting this up. This might actually replace my regular jumps to as it's still a bit faster to get to things by class compared to searching for the file. I've already added it to my browser startpage: 

post-874-0-84504400-1454502284_thumb.png

  • Like 1

Share this post


Link to post
Share on other sites

....methods and such found via this are not necessarily intended as public API, and may be subject to change in later versions,

Nice line about potential future changes. Added it to the readme :-)

....In the dark theme especially the dark lines tend to disappear, and some of the colors (such as the red headers) kind of make my eyes ache.

The whites make my eyes ache  :P . I'll look into setting up a theme switcher.

  • Like 2

Share this post


Link to post
Share on other sites

the search could maybe be a great help if it worked :)

It works just fine :-)...but not always as, .....erm, clearly stated here  :P

Known Bugs

  • Some pages generated with extra ... just before the HTML suffix, resulting in 404s. Upgrading to a newer version of ApiGen will probably fix this. In the meantime, delete the extra ... in the URL and you are good to go.
  • Like 2

Share this post


Link to post
Share on other sites

Very nice! - ähm but unfortunately not my colors. Ough. Please can we have a less colorful theme or a theme switcher with one less colorful, once all other is running? please, please, please, ... :)

  • Like 1

Share this post


Link to post
Share on other sites

I think this I the type of project where a stock CSS framework design would perfectly fit - eg. Uikit.

Share this post


Link to post
Share on other sites

@tpr

Apigen is a ready made dokumentation generator. The markup/classes are probably not very customizable, so using a framework wouldn't solve much. It's more about finding/creating a color scheme.

Share this post


Link to post
Share on other sites

Update: Theme Switcher :-) + remake of dark theme

OK, because you all asked nicely, and because I don't want @teppo's eyes aching (although he might have been looking at my theme through his cool sunglasses  ;) ) and because I don't want @horst to feel 'Ough', I have hurried this up :P  :lol: . OK, jokes aside...

Theme switcher now included (quite a trivial thing really). The default is the light theme that ships with APIGEN (actually, it also has a Bootstrap theme that it ships with). If you prefer the dark theme (I've gone easy on some colours), just click on the dark box. It will set a cookie and remember you...for a whole year!! If on the light theme, no cookies for you, sorry :-). When I get time I will write those EU cookie thingys. Something like 'if you are visiting me and would like to stay in a room surrounded by cool, then you must accept to eat my cookies! What do you mean you don't like my cookies? What's wrong with my cookies!? If you don't like my cookies then you stay in the light room'....OK, a bit OTT there (I had a WillyC moment, but failed miserably...am trying too hard, I know :biggrin: )...

Btw, there's the occasional flash of  'light theme' when surfing using the dark theme. Am not too bothered about it so will let it be for now..

Anyway, update's here

Later..

  • Like 6

Share this post


Link to post
Share on other sites

In case you haven't noticed, you can shift+click to select a block of code lines, or ctrl+click to select multiple lines. Also, the left side menu just doesn't list the classes, but functions and interfaces as well. Really cool.

I have been trying to find a way of displaying the full version numbers of each branch with the docs but haven't found way. For now, if you want to know the version, just scroll or search for the Class ProcessWire. and look at the constants summary table.

  • Like 1

Share this post


Link to post
Share on other sites

And we are all up :-). Initial versions of dev and devns are both up now. Don't worry, I won't be giving a running commentary every week! Needed to test that everything works smoothly and so far no hiccups. 

post-894-0-77036600-1454606105_thumb.png

  • Like 6

Share this post


Link to post
Share on other sites

hi kongondo,

just wanted to say thank you again how awesome this apigen is!!! want to know all hookable methods in a class? easy as using your search...

post-2137-0-38422200-1456245801_thumb.pn

  • Like 4

Share this post


Link to post
Share on other sites

hi kongondo,

just wanted to say thank you again how awesome this apigen is!!! want to know all hookable methods in a class? easy as using your search...

attachicon.gif2016-02-23 17_41_45-File modules_Process_ProcessPageEdit_ProcessPageEdit.module _ ProcessWire API (m.png

In Sublime Text i can do this by quick search "inputfield.php@___" ;)

  • Like 2

Share this post


Link to post
Share on other sites

Bit of an update, we are back in play with this one. Moved the doc-generation tasks to a remote server for reliability. PW 2.7 docs stay, although not getting updated, obviously. PW 2.8 and 3 branches getting regular automated doc-generation. 

  • Like 4

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now


  • Recently Browsing   0 members

    No registered users viewing this page.