I need a CMS to act as documentation for a code library

November 24, 2004 12:15 AM

CMS Filter: You would've thought we could have covered every possible CMS topic by now, but I've got what I think is a new twist. I need a CMS to act as documentation for a code library. [mi]

I'm developing a code library to act as a basic rapid development environment for programmers I have working for me. I need to develop some documentation. It'll have to include examples. What I would like is a CMS that comes out of the box able to display blocks of PHP code with the same #ccc background and colored text that the www.php.net documentation uses. ... ... But my google-fu can't seem to find one, and I feel kind of like an idjit. Any suggestions?

posted by SpecialK to computers & internet (7 comments total)

rename your .php files to .phps

if you've got the proper MIME types set up in apache, PHP will automatically parse and display them in formatted source
posted by cheaily at 1:11 AM on November 24, 2004

It's not that I want to *display* my source for all to see, I want to take snippets out and provide examples of use and documentation, in exactly the way the PHP documentation does; i.e. This PHP docs page. And if I were to want to display a whole file inline in the docs, I could use highlight_file() ... or highlight_string().
However, I'd like a nice tidy CMS to take care of all of this for me, because this documentation site will get quite large ... and I need some way to control and manage revisions, etc.
posted by SpecialK at 1:23 AM on November 24, 2004

you might find searching for "literate programming" useful (along with "php").
posted by andrew cooke at 4:12 AM on November 24, 2004

Something like ...

I use open wiki for my code repository, and it has a special "code" tag which does just this. e.g. {{{your code here}}}
If you have a different CMS you want to use, then you could update the css for the <cite> tag to box up code and put it in a non-proportional font.
{font-family:Lucida Console,Courier New,Courier,monospace; color:#666666; background-color:#ffffff;}
posted by seanyboy at 4:35 AM on November 24, 2004

*sigh* Andrew, that. won't. work. Let me be a little clearer: I want to document some code libraries without providing actual access to said code libraries. Therefore, any documentation that I provide in comments will most likely never, ever get read by the people I'm writing these docs for. That's also why using the built in .phps won't work.

Seanyboy: Thanks, that was very useful. There's a Wiki out there that will do what I want, but the download page got ./'d or something and I just get an "over bandwidth limit" error. :( ... so that's a great alternative.
posted by SpecialK at 8:23 AM on November 24, 2004

It's not a CMS, but you might want to look into something like phpDocumentor.
posted by sad_otter at 10:19 AM on November 24, 2004

Woohoo! I found one. DocuWiki is a very nice wiki that meets my needs pretty well, and it works with AuthType Basic to control permissions and access automatically. I can even use the .htpasswd file that I use to control access to the development sandboxes to control user permissions.
posted by SpecialK at 10:44 AM on November 24, 2004