Hi Michael,

I had a poke around with the description problem, you are right that it is annoying that we document this with comments inside the dictionary (pydoc can't capture these). What you could do is move the documentation to the pydoc string attached to the configuration object (VLAN, or ACL, etc). However this does make it less obvious when reading the source code what is going on.

Otherwise, it is possible to capture the descriptions from the "defaults" dictionary without regex. Admittedly this isn't a very elegant solution but you can combine inspect.getsourcelines() with some bad list comprehension to get the data out:

        lines = inspect.getsourcelines(VLAN)[0]
        start_index = next(i for i, s in enumerate(lines) if 'defaults = {' in s) + 1
        stop_index  = next(i for i, s in enumerate(lines[start_index:]) if '}' in s) + start_index
        for line in lines[start_index:stop_index]:
            print(line.strip())


This will give you a list of descriptions and configuration elements.

I'll leave it up to you to pick out the most elegant solution here....

Thanks!
Brad

On Fri, Jan 19, 2018 at 4:10 PM, Michael Baird <Michael.Baird@ecs.vuw.ac.nz> wrote:
Thanks guys,

I've extended Shivaram's version to also get the type, and generate a CSV that can be included in the rst.
Just missing static routes, failover and top level tables.

It doesn't include a description unfortunately. Any ideas for that? - Another dictionary? Class/Method docstring?
And some types loose information. e.g. Original "tagged_vlans - list of integers or strings". New tagged_vlans - list

So one step forward two back.

Updated script and output html attached.

Michael.


On 18/01/18 18:54, Shivaram Mysore wrote:
Attached is the version that I have - not executed this in some time.  

/Shivaram

On Wed, Jan 17, 2018 at 9:31 PM, Brad Cowie <brad.cowie@waikato.ac.nz> wrote:
Hi Michael,

I wonder if using Python Introspection to lookup the values in 'defaults' and 'defaults_type' might be more robust to future code changes than using regex.

I wrote an early version of a script to do this that Shivaram extended and added more features too, maybe this might help inspire a second version of your docs_parser.py?

https://gist.github.com/shivarammysore/b559731651b938635b630f0d9fe8b065

Brad

On Thu, Jan 18, 2018 at 5:57 PM, Michael Baird <Michael.Baird@ecs.vuw.ac.nz> wrote:
Ok, I've got a script that generates a table similar to http://docs.faucet.nz/en/latest/configuration.html#dp from whatever files is given to it.

Basically it looks for 'defaults' and 'defaults_types' and uses the comment below it as the description.
And converts everything to a csv.

Was thinking the 'default' could be overridden with a comment on the same line. e.g. dp_id

See attached html dp, vlan & interface


Script: https://github.com/Bairdo/faucet/blob/doc-script/docs/docs_parser.py



On 18/01/18 14:54, Josh Bailey wrote:
They're manually generated at the moment.

Documentation fixes always welcome (as are scripts to generate doc/snippets from code!).

Thanks,

On Thu, Jan 18, 2018 at 2:51 PM, Michael Baird <Michael.Baird@ecs.vuw.ac.nz> wrote:
Hi,
Are the configuration tables in https://faucet.readthedocs.io/en/latest/configuration.html generated via script from the codebase or manually?

There is a couple of options that look wrong or are missing (in particular hairpin & loop_protection). If its manual I'll update them.

Thanks,
Michael.
_______________________________________________
Faucet-dev mailing list
http://faucet.nz/
Faucet-dev@list.waikato.ac.nz
https://list.waikato.ac.nz/mailman/listinfo/faucet-dev



_______________________________________________
Faucet-dev mailing list
http://faucet.nz/
Faucet-dev@list.waikato.ac.nz
https://list.waikato.ac.nz/mailman/listinfo/faucet-dev



--
Wand Group
Department of Computer Science
The University of Waikato

Phone: +64 7 858 5267
Mobile: +64 27 5888 103
Office: G.1.01

_______________________________________________
Faucet-dev mailing list
http://faucet.nz/
Faucet-dev@list.waikato.ac.nz
https://list.waikato.ac.nz/mailman/listinfo/faucet-dev





--
Wand Group
Department of Computer Science
The University of Waikato

Phone: +64 7 858 5267
Mobile: +64 27 5888 103
Office: G.1.01