[Fuego] RFC - test/set/case documentation generation

Gustavo Sverzut Barbieri barbieri at profusion.mobi
Thu Feb 8 18:53:46 UTC 2018


>> > Please let me know what you think.
>>
>> Hi Tim, looks nice but my advice is to avoid pre-processing the rst
>> (your ftmp format) and instead use reStructuredText and add your own
>> directives, it's already meant for that.
>
> You may notice that my "macro" actually has the same syntax as
> an reStructuredText directive.  This was done specifically to allow
> the possibility of converting over to the flow of processing that
> you mention below.

sure, but then keep the same extension (so github/bitucket...) handle
it properly. And also note the final "::" (two), otherwise it's
handled as comment (leading ".." without trailing "::")



> As an aside, what does Sphynx do with directives it doesn't recognize?
> (Sorry - I'm too lazy to go test is right now, but if someone knows
> off the top of their head please let me know.)

not sure, I never tried that... but I guess it will report errors and
keep going. Github/Bitbucket keep it untouched (you see the actual
text).


>> I'd even go further and say that's better to setup an sphinx for the
>> project and create your own extension, then you can provide those as
>> needed AND scan for files in the directory structure. For example
>> Python's autodoc and the does something like that for python modules.
>>
>> Initially you can avoid much of the burden by:
>>
>>  - start sphinx project in the root directory
>>  - manually link the child .rst until you create your own autoindex
>> kind of function
>>  - in the child .rst you .. literalinclude:: results from some
>> directory until you create your own directives or roles
>>
>> with that, no gen-pages is needed, just run the tests (to populate the
>> directories with results you're including as "literalinclude") and it
>> should produce the contents.
>>
>> then you can create your sphinx extension (inside this repository,
>> just list it in the sphinx config) and start to provide the directives
>> and macros... they can do lots of stuff, like generate tables and
>> other sphinx formatting (ie: there are modules that does syntax
>> highlight using pygments). You can receive parameters in them, and you
>> can get the file/path of the file being processed, so you can discover
>> the test name and all.
>
> Thanks very much for the feedback.  I am by no means sure that the
> approach I have taken is optimal, so I really appreciate other ideas
> for implementing this.
>
> With regard to sphynx, I definitely want to make it a first-class tool
> in our container, and possibly add fuego-specific extensions (directives) to it.
> I took a look yesterday at how to write extensions for it, and they
> look powerful, and straightforward to write.  I've already started moving
> the regular Fuego documentation over to reStructuredText, but I don't
> recall if I've made the changes to include sphynx in the Dockerfile yet.
>
> I'll think more about your suggestion as I keep working on this.

you're welcome. It's a bit steep learning curve to get started
(compared to plain python + readlines + regexp), but at the end it
pays off. With some days looking into that, you can get it going.
There's not much documentation, but you can look the source of similar
extensions to see how things work (that's how i learnt).

you get called with a list of options + body... after that, just
return the rst "ast"... you can either create on manually, using
elements such as "paragraph" or generate a text string and ask it to
be parsed (ie: when you do a quote block: generate a new toplevel
element yourself (blockquote) then ask it to parse the contents), this
is self.state.nested_parse() from your directive...

then everything else is handled for you, output to LaTeX/PDF, HTML,
manpage, etc...


-- 
Gustavo Sverzut Barbieri
http://profusion.mobi embedded systems
--------------------------------------
MSN, GTalk, FaceTime: barbieri at gmail.com
Skype: gsbarbieri
Mobile: +55 (16) 99354-9890


More information about the Fuego mailing list