[erlang-questions] HTML/CSS/Javascript in Erlang docs and Common Test

Jean Parpaillon <>
Wed Mar 2 14:07:28 CET 2016


Hi,

Le mercredi 02 mars 2016 à 21:58 +0900, zxq9 a écrit :
> On Wednesday 02 March 2016 12:38:52 Ali Sabil wrote:
> > Thank you for bringing this up. An improvement to the presentation
> > of the
> > Erlang documentation is very much needed.
> > 
> > I have started looking at this myself sometime ago, here is what I
> > gathered:
> >     • The OTP documentation is using erl_docgen which is mostly
> > XSLT based
> >     • Edoc is not that much used in OTP, the applications that do
> > rely on
> > it, use a custom layout (otpsgml_layout) to generate output that
> > can be
> > consumed by erl_docgen.
> >     • Experimented with adding a modern HTML5 output to erl_docgen
> > here:
> > https://github.com/asabil/otp/tree/feature/html5-docs but this prov
> > ed
> > itself challenging.
> >     • Started working on a modern doclet for edoc, based on the
> > ex_doc
> > layout: https://bitbucket.org/asabil/edoc-modern
> 
> Hi Ali,
> 
> I ran into the exact same thing and concluded it would be easier to
> treat
> rendered docs as their own data source rather than try to decobble
> all the
> mix-and-match that exists within the OTP sources themselves (though
> the
> *right* approach would be to actually make the docs across OTP
> uniform --
> I felt this would be futile to even attempt alone and unsupported,
> who has
> that much (un)paid time on their hands?).
> 
> Tricky, to say the least.
> 
> -Craig

The approach I've had with mkdocs is to translate into more-or-less
standard documentation intermediate format, like mkdocs or *cough*
docbook ;)
This would have the advantage of benefiting from existing ecosystem and
let uniformity come later (we could later develop a specific mkdocs
theme, for instance).


My 2c,


> _______________________________________________
> erlang-questions mailing list
> 
> http://erlang.org/mailman/listinfo/erlang-questions
-- 
Jean Parpaillon
--
Director @ OW2 Consortium
OCCIware Strategic Orientation Committee Chairman
Research Engineer @ Inria
--
Phone: +33 6 30 10 92 86
im: 
skype: jean.parpaillon
linkedin: http://www.linkedin.com/in/jeanparpaillon/en



More information about the erlang-questions mailing list