Vidola: building documentation

Coding Critique is the place to post source code for peer review by other members of DevNetwork. Any kind of code can be posted. Code posted does not have to be limited to PHP. All members are invited to contribute constructive criticism with the goal of improving the code. Posted code should include some background information about it and what areas you specifically would like help with.

Popular code excerpts may be moved to "Code Snippets" by the moderators.

Moderator: General Moderators

Vidola: building documentation

Postby koen.h » Thu Jul 12, 2012 1:41 pm

Hope to get more feedback than with my previous library fjor :D

I've been working hard at making documentating coding efforts as easy as possible. The result is Vidola. It allows to write your in an easy format (a Markdown extension) and transfrom this to documentation for the project.

Of course I eat my own dog food. Here is an example page written for Vidola:

https://github.com/koenhoeymans/Vidola/ ... aryUse.txt

And here you can find the result after going throug the Vidola library:

http://koenhoeymans.github.com/Vidola/LibraryUse.html

I believe I'm at a stage where I can start to show what I'm working at.

Any criticism, suggestions, remarks are appreciated, about the code or anything else. :)
koen.h
Forum Contributor
 
Posts: 268
Joined: Sat May 03, 2008 8:43 am

Re: Vidola: building documentation

Postby Christopher » Thu Jul 12, 2012 3:48 pm

The thing about these systems is that the reason to keep the content in markdown is so you can generate multiple outputs (e.g. HTML, PDF, Window Doc, manpage, etc.). If that's not the goal and all it does is convert markup then it is just one extra layer. So why not just use HTML?
(#10850)
User avatar
Christopher
Site Administrator
 
Posts: 12681
Joined: Wed Aug 25, 2004 7:54 pm
Location: New York, NY, US

Re: Vidola: building documentation

Postby koen.h » Thu Jul 12, 2012 11:41 pm

I started with HTML and it didn't feel like writing documentation should feel. I could live with writing tags but writing about code proved too annoying. Same with docbook.
koen.h
Forum Contributor
 
Posts: 268
Joined: Sat May 03, 2008 8:43 am

Re: Vidola: building documentation

Postby koen.h » Fri Jul 13, 2012 12:48 pm

I've updated the documentation to try to give an answer:

http://koenhoeymans.github.com/Vidola/A ... use-vidola

Thank you for expression your view btw.
koen.h
Forum Contributor
 
Posts: 268
Joined: Sat May 03, 2008 8:43 am

Re: Vidola: building documentation

Postby Christopher » Fri Jul 13, 2012 2:14 pm

I guess I was wondering why someone should add an extra build step to their documentation and also need to learn a new syntax when they already know HTML -- just because "Writing ____ in HTML is annoying."
(#10850)
User avatar
Christopher
Site Administrator
 
Posts: 12681
Joined: Wed Aug 25, 2004 7:54 pm
Location: New York, NY, US

Re: Vidola: building documentation

Postby koen.h » Fri Jul 13, 2012 2:43 pm

Christopher wrote:I guess I was wondering why someone should add an extra build step to their documentation and also need to learn a new syntax when they already know HTML -- just because "Writing ____ in HTML is annoying."


Hehe, I prefer this extra build step to be done programatically and not manually by typing "<" everytime. The extra build step is either using Vidola , or manually writing HTML around the documentation and converting entities when writing about PHP and/or HTML. I think in both ways this step is done.

That brings me to the second argument. I believe learning (and how much is there to learn?) Markdown is worth the effort compared to a lifetime of converting entities within code tags.
koen.h
Forum Contributor
 
Posts: 268
Joined: Sat May 03, 2008 8:43 am

Re: Vidola: building documentation

Postby Christopher » Fri Jul 13, 2012 3:35 pm

Ok ... I am just pestering you to see how strong you reasons are. It looks like an interesting library. Have you separated the pure Markdown parser from the documentation part so it can be used stand-alone?
(#10850)
User avatar
Christopher
Site Administrator
 
Posts: 12681
Joined: Wed Aug 25, 2004 7:54 pm
Location: New York, NY, US

Re: Vidola: building documentation

Postby koen.h » Sat Jul 14, 2012 3:46 am

Yes it is separated:

https://github.com/koenhoeymans/Vidola/ ... placer.php

It uses a list of patterns, pre/post processors to get the job done. So it is customizable also. I decided on using the power of PHP DOM. Disadvantages of this approach were that it does nasty thing with entities on moments you don't want it. The speed of processing is probably also very very low.
koen.h
Forum Contributor
 
Posts: 268
Joined: Sat May 03, 2008 8:43 am

Re: Vidola: building documentation

Postby koen.h » Mon Dec 10, 2012 7:00 am

For those interested: the Markdown parser will live in its own repo. Started the founding work for that.

https://github.com/koenhoeymans/AnyMark
koen.h
Forum Contributor
 
Posts: 268
Joined: Sat May 03, 2008 8:43 am

Re: Vidola: building documentation

Postby Christopher » Mon Dec 10, 2012 11:14 pm

Just looked at the code a little. Does AnyMark need a dependency on Fjor? Or is there another way to achieve this outside of AnyMark?
(#10850)
User avatar
Christopher
Site Administrator
 
Posts: 12681
Joined: Wed Aug 25, 2004 7:54 pm
Location: New York, NY, US

Re: Vidola: building documentation

Postby koen.h » Tue Dec 11, 2012 2:33 am

Christopher wrote:Just looked at the code a little. Does AnyMark need a dependency on Fjor? Or is there another way to achieve this outside of AnyMark?


It does need Fjor. It would not be much work to wire it by hand and add this as an option. However, Fjor is also used for instantiating the patterns. I don't know if anyone could be bothered to create these manually and add them to the \AnyMark\Pattern\PatternList.
koen.h
Forum Contributor
 
Posts: 268
Joined: Sat May 03, 2008 8:43 am

Re: Vidola: building documentation

Postby koen.h » Thu Dec 20, 2012 3:13 pm

Christopher wrote:Just looked at the code a little. Does AnyMark need a dependency on Fjor? Or is there another way to achieve this outside of AnyMark?


I've added to possibility to install through composer. Maybe that makes it easier not to care about Fjor since that is taken care of automatically by composer.

https://packagist.org/packages/anymark/anymark

edit:

Syntax: [ Download ] [ Hide ]
require 'vendor/autoload.php';

$text = '**a**';

$am = \AnyMark\AnyMark::setup()->get('AnyMark\\AnyMark');

var_dump($am->saveXml($am->parse($text)));
koen.h
Forum Contributor
 
Posts: 268
Joined: Sat May 03, 2008 8:43 am


Return to Coding Critique

Who is online

Users browsing this forum: No registered users and 2 guests