User Contributed Documentation


#1

I have seen others post about the severe lack of documentation here and I think I have the answer. The answer is to have the regular documentation as is, but also allow users to comment on each function or class. This would allow us to include examples and point out bugs in a context specific way.  Similar to how it works at php.net. I believe that most of the success of PHP has been due to its awesome user contributed documentation.  I'd actually be kinda interested in working on the project of implementing it if I knew it would be availble here in plain sight and if others also thought it was a good idea and would be interested in submitting documetation and examples.

 


#2

A wiki? :)

 

http://www.juce.com/forum/topic/juce-wiki-attempt-2

 

 


#3

With the new drupal website, I think (though I'm not much of a drupal expert!) that I can grant access for trustworthy people to add content as real pages, which should be a lot nicer than a wiki.. If anyone wants to volunteer, let me know!


#4

Actually there's two things you could do:

 

1) what you are suggesting.  Create a low-power (Filtered HTML/bbcode only) user group and allow them to create content.  hook_cron() can be used to auto-promote regular users to 'creator' class once their post count reaches a certain threshold, so this could be pretty much zero-admin.

2) A chunk more work, but more flexible: have a post-process script that takes Doxy output and creates Drupal nodes for the various pages[1].   If these nodes are created with a specific node type then you can create a group that has comment permissions for the documentation nodes,  and use an approach like #1 to enroll users into the documentation comments group.

 

Personally I'd go for #2, not just because it's the kind of Drupal project that tends to catch my own attention (lots of stuff in our lab is Drupal powered, and often that's because I was bored one evening), but because in the long run this provides a pretty limitless basis for extending out what can be done with documentation and wiki pages.  The Drupal documentation pages themselves give some idea as to how this could work (although they've set their stuff up in a way that does rather sprawl).

 

 

[1] The documentation would not necessarly even need to be represented as a node, as a custom node module can scrape the corresponding Doxy HTML file and extract the relevant HTML directly.  In this way, each node is just a stub with a field that links to a Doxy page somewhere outside of the world reachable http document space.

 


#6

Wow - sounds great, but I don't currently have any spare intellectual capacity to go up such a steep drupal learning curve! Any volunteers? ;)


#7

Depends on how much volunteering is needed. ;)

I'd be perfectly happy to do knock up some custom Drupal modules.  There's some overlap with some other projects I have in my pipeline.  This is all stuff I can do very rapidly.

The Drupal stuff is not the big work unit however.  

Giving this a bit more thought, IMV the best approach would be to have Doxy ouput XML and use XML parsing in PHP to build a keyword index, followed by XSLT to create a node body.  

Someone with far more experience with XSLT, and/or familiarity with Doxygen's XML schema would probably make reasonably light work of this.  

If there's any community interest in picking parts of this up, I'll volunteer some time (albeit not before mid-November at the earliest).  Handling the whole deal seems like a bit of a mouthful for evening work given my current schedule though. :)

 

 

 


#8

Thanks! I'm juggling too many other complicated things right now to be able to drive this, but maybe in a few weeks time...


#9

All of these ideas are great. Wikis, drupal modules. What I was initially suggesting was really just something that adds commenting support to the existing doxygen documentation. Maybe something that runs afterwards and adds small php blocks after each function listing that has the ability to add comments and lists existing ones. Storing the comments maybe in an sqlite database that sits along side.  If it is important to keep the doxygen generated files static then it could be done with javascript that talks to a simple api server side.

Maybe today I'll grab one of the longer doxygen generated html files and see if i can create the javascript and php serverside and put it up somewhere as a demo.


#10

Please, don’t make this dependent on php!
I can imagine I am not the only one also pulling the doxygen documentation and accessing it locally with just a browser!
I’m not online 24/7, so I am dependent on having it locally available, without any more string attached!


#11

well. if it was done the javascript way, then it wouldnt be dependent upon anything. if you were connected to the internet it would request the comments .. if you werent online.. it would appear the same as it does now. The pages already include jquery and some kind of search javascript. Im not famliar enough with doxygen to know exactly how to tell it to include one more javascript file, but I dont see it as being much of an issue.


#12

Alright, so. I setup a rudimentary demo of what i was talking about.

If you scroll down to where the detailed descriptions of member functions are you'll see that I already added a few 'Notes'.

Initially, the notes are hidden and it just shows the count.

I have it setup right now to approve everything. Ideally, someone would moderate the stuff at their leisure.

Ill Toss the code up on github soon.

http://www.jackanderson.net/jucedoc/classComponent.html


#13

ok, here's the code. it's pretty basic and probably needs some kind of administation tool beyond the sqlite commandline :)

Instead of approval, some kind of captcha could also be implemented. Also, care would have to be taken so doxygen doesnt overwrite the sqlite file every time it reprocesses. That could be mitigated by keeping it in a different location or using mysql.  The php api uses PDO for its database operations, so it should work fine with another RDMS. Of couse, bbcode support should probably be added as well.

https://github.com/jackanderson/jucenotes


#14

nstead of approval, some kind of captcha could also be implemented

This is exactly why doing this in Drupal is a better long term approach IMV.  Drupal is already taking care of the security, SQL injection attack, XSRF attack stuff, managing user profiles/permissions, and has modules to do further spam catching.  Rolling all of this again, simply means more work, more risk, more complexity when updating to the next version of Drupal, and the theme still doesn't match that of the main site.

Further, at the end of it, the indexing generated by the importer will be known to Drupal, which allows for more adanced features over time.  

An obvious example would be to allow for custom tags in this forum that auto link to the corresponding documentation page, E.G.

[[graphics::paint]] 

Which would create an auto link to the paint() method in the Graphics page.

 

There are always ways to get something going quickly, and often that's the right approach as you can always iterate later.  I'm far from convinced stuff that takes user input on the web is one of those cases however.

 

 

 


#15

lucem, 

 

neither what I'm proposing or what Jack is proposing need break offline doxy support, they're just different approached to enriching the online version (to say nothing of the fact that you're always free to create your own local doxy HTML directly from source).


#16

The problem with doing it with drupal is that drupal is php and the doxygen generated pages are static html (for speed , portability and low cpu footprint). Though since the API server that I wrote is php, it would be rather trivial to tie it into drupal if needbe. The thing I made was really not much more than a proof of concept. The code is freely available at the link I posted. If you'd like to try your hand at making the API server a drupal module, be my guest. You should be able to just instantiate the NoteApi class I wrote , pass in drupal's PDO instance and check to see if the user is logged in. The commenting stuff itsself pretty much has to remain javascript. Oh, also, just to be clear, I was careful to prevent SQL injection and cross site scripting attacks. I did not however prevent cross site forgery. Just didnt get around to it.


#17

One more thing, I think part of the reason PHP's user contributed documentation is so successful is because it doesnt require you to have an account to submit or to view the annotations. It is just there and easily accessible. The drawback is that every post must be approved by someone. They are clear that it is not a question forum and that it is for documentation purposes.


#18

doxygen generated pages are static html.

Doxygen can also spit out XML.  In that way you're not getting a page of static HTML with extra formatting and meta cruft.  Extracting content from the XML is way easier than dealing with the Doxy HTML (not least of which because Doxygen makes no guarantees about the structure and class identifiers in th HTML, so updates could easily break extraction code).

 

Actually generating HTML that Drupal can inline into a node can (probably) subsequently be performed on the XML by using an XSLT.   This gives you a process something like:

 

Run doxygen: (configured to generate HTML and XML).

Push the HTML to the server as a zip (Jules is already doing this so I'm assuming there's a script already written).

Push the XML to the server.  A Drupal module can present a web-service for receiving this.  Or a cron-job can simply sniff an inbox dir periodically.

The Drupal module marks all documentation nodes as stale, then it parses the XML.  As it goes, it:

  • tests to see if a node matching the current class/namespace exists, and if so updates it and marks it not stale, otherwise, a new node is created.  In either case, the node body is an XSLT of the class XML.  
  • updates a keyword lookup index to match detected keywords to the given node/anchor pair (see below).

Finally, any still stale nodes are deleted.

At that point, Drupal basically does everything else for free.  The searching will be inefficient by default, but will be site wide.  The module can also augment the search functionality directly if needed, using is own keyword table, to update Drupal's search system (https://api.drupal.org/api/drupal/modules%21search%21search.module/group/search/7)

 

Because each class is presented as a normal node, you get essentially this forum system on each and every entry in the documentation.

 

  


#19

I should have replied to this sooner. I found it really easy to parse out the member names and sections from the doxy pages using jQuery. If it had to be done on the php side, the css  selectors I searched for could very easily be converted to xpath queries (http://php.net/manual/en/simplexmlelement.xpath.php). No XSLT required.


#20

My only real concerns with that would be the extra cpu load that would be required in having all of the documentation pages be php and that full forum support is unnecessary for simple annotations in the documentation. Often times when I come to this drupal site it is gruelingly slow, it would suck to have to deal with that when trying to peruse the docs.  I hear you about the css selectors, but as far as i know the only one that is important is .memname and it doesnt appear to have ever changed. Anyways, we need something. Forums are relatively useless for quick reference and the existing docs lack real world examples. The demo app helps, but it doesnt cover everything and is not particularly easy to navigate in a pinch.