giscanner: Add a simple automatic sections file generator

This is a very basic sections file generator, and isn't too smart.
It's simply intended to be a base to build docs on, and will be used
if the user doesn't provide a sections file when calling g-ir-doc-tool,
for convenience purposes.

https://bugzilla.gnome.org/show_bug.cgi?id=699856

5 files changed, 445 insertions, 3 deletions

diff --git a/.gitignore b/.gitignore
index 7d1776db..1ed05a4a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -133,3 +133,5 @@ docs/reference/version.xml
 #g-ir-doc-tool tests
 *.page
 !tests/scanner/*-expected/*.page
+*-sections.txt
+!tests/scanner/*-sections-expected.txt
diff --git a/giscanner/docmain.py b/giscanner/docmain.py
index 3287dcc6..e65b57a0 100644
--- a/giscanner/docmain.py
+++ b/giscanner/docmain.py
@@ -22,6 +22,7 @@ import os
 import optparse
 
 from .docwriter import DocWriter
+from .sectionparser import generate_sections_file, write_sections_file
 from .transformer import Transformer
 
 
@@ -38,6 +39,9 @@ def doc_main(args):
     parser.add_option("", "--add-include-path",
                       action="append", dest="include_paths", default=[],
                       help="include paths for other GIR files")
+    parser.add_option("", "--write-sections-file",
+                      action="store_true", dest="write_sections",
+                      help="Generate and write out a sections file")
 
     options, args = parser.parse_args(args)
     if not options.output:
@@ -55,7 +59,14 @@ def doc_main(args):
     extra_include_dirs.extend(options.include_paths)
     transformer = Transformer.parse_from_gir(args[1], extra_include_dirs)
 
-    writer = DocWriter(transformer, options.language)
-    writer.write(options.output)
+    if options.write_sections:
+        sections_file = generate_sections_file(transformer)
+
+        fp = open(options.output, 'w')
+        write_sections_file(fp, sections_file)
+        fp.close()
+    else:
+        writer = DocWriter(transformer, options.language)
+        writer.write(options.output)
 
     return 0
diff --git a/giscanner/sectionparser.py b/giscanner/sectionparser.py
index 61763e45..6a6a231c 100644
--- a/giscanner/sectionparser.py
+++ b/giscanner/sectionparser.py
@@ -18,6 +18,8 @@
 #
 
 import re
+from . import ast
+from .utils import to_underscores
 
 
 class SectionsFile(object):
@@ -89,3 +91,60 @@ def parse_sections_file(lines):
         current_subsection.symbols.append(line)
 
     return SectionsFile(sections)
+
+def write_sections_file(f, sections_file):
+    for section in sections_file.sections:
+        f.write("\n<SECTION>\n")
+        if section.file is not None:
+            f.write("<FILE>%s</FILE>\n" % (section.file, ))
+        if section.title is not None:
+            f.write("<TITLE>%s</TITLE>\n" % (section.title, ))
+        if section.includes is not None:
+            f.write("<INCLUDE>%s</INCLUDE>\n" % (section.includes, ))
+
+        is_first_subsection = True
+        for subsection in section.subsections:
+            if subsection.name is not None:
+                f.write("<SUBSECTION %s>\n" % (subsection.name, ))
+            elif not is_first_subsection:
+                f.write("\n<SUBSECTION>\n")
+
+            is_first_subsection = False
+
+            for symbol in subsection.symbols:
+                f.write(symbol + "\n")
+
+def generate_sections_file(transformer):
+    ns = transformer.namespace
+
+    sections = []
+
+    def new_section(file_, title):
+        section = Section()
+        section.file = file_
+        section.title = title
+        section.subsections.append(Subsection(None))
+        sections.append(section)
+        return section
+
+    def append_symbol(section, sym):
+        section.subsections[0].symbols.append(sym)
+
+    general_section = new_section("main", "Main")
+
+    for node in ns.itervalues():
+        if isinstance(node, ast.Function):
+            append_symbol(general_section, node.symbol)
+        elif isinstance(node, (ast.Class, ast.Interface)):
+            gtype_name = node.gtype_name
+            file_name = to_underscores(gtype_name).replace('_', '-').lower()
+            section = new_section(file_name, gtype_name)
+            append_symbol(section, gtype_name)
+            append_symbol(section, node.glib_type_struct.target_giname.replace('.', ''))
+
+            for meth in node.methods:
+                append_symbol(section, meth.symbol)
+            for meth in node.static_methods:
+                append_symbol(section, meth.symbol)
+
+    return SectionsFile(sections)
diff --git a/tests/scanner/Makefile.am b/tests/scanner/Makefile.am
index 133dfaad..a2276929 100644
--- a/tests/scanner/Makefile.am
+++ b/tests/scanner/Makefile.am
@@ -152,7 +152,7 @@ Headeronly-1.0.gir: headeronly.h
 
 if BUILD_DOCTOOL
 DOCGIRS = Regress-1.0.gir
-CHECKDOCS = $(DOCGIRS:.gir=-C.page.check) $(DOCGIRS:.gir=-Python.page.check) $(DOCGIRS:.gir=-Gjs.page.check)
+CHECKDOCS = $(DOCGIRS:.gir=-C.page.check) $(DOCGIRS:.gir=-Python.page.check) $(DOCGIRS:.gir=-Gjs.page.check) $(DOCGIRS:.gir=-sections.txt.page.check)
 MALLARD_DIRS = $(DOCGIRS:.gir=-C) $(DOCGIRS:.gir=-Python) $(DOCGIRS:.gir=-Gjs)
 MALLARD_CLEAN = $(DOCGIRS:.gir=-C)/* $(DOCGIRS:.gir=-Python)/* $(DOCGIRS:.gir=-Gjs)/*
 EXPECTED_MALLARD_DIRS = $(MALLARD_DIRS:=-expected)
@@ -173,6 +173,10 @@ CLEANFILES += $(MALLARD_CLEAN)
 	$(AM_V_at)-rm -rf $(builddir)/$*-Gjs
 	$(AM_V_at)$(INTROSPECTION_DOCTOOL) $(INTROSPECTION_DOCTOOL_ARGS) --language Gjs $*.gir -o $(builddir)/$*-Gjs/
 
+%-sections.txt: %.gir
+	$(AM_V_GEN)
+	$(AM_V_at)$(INTROSPECTION_DOCTOOL) $(INTROSPECTION_DOCTOOL_ARGS) --write-sections-file $*.gir -o $@
+
 %-C.page.check: %-C
 	@diff -r -u -w -B -U 10 $(srcdir)/$*-C-expected $(builddir)/$*-C && echo "  TEST  $*-C"
 
@@ -181,6 +185,10 @@ CLEANFILES += $(MALLARD_CLEAN)
 
 %-Gjs.page.check: %-Gjs
 	@diff -r -u -w -B -U 10 $(srcdir)/$*-Gjs-expected $(builddir)/$*-Gjs && echo "  TEST  $*-Gjs"
+
+%-sections.txt.page.check: %-sections.txt
+	@diff -u -w -B -U 10 $(srcdir)/$*-sections-expected.txt $*-sections.txt && echo "  TEST  $*-C"
+
 else
 CHECKDOCS =
 endif
diff --git a/tests/scanner/Regress-1.0-sections-expected.txt b/tests/scanner/Regress-1.0-sections-expected.txt
new file mode 100644
index 00000000..96df7c59
--- /dev/null
+++ b/tests/scanner/Regress-1.0-sections-expected.txt
@@ -0,0 +1,362 @@
+
+<SECTION>
+<FILE>main</FILE>
+<TITLE>Main</TITLE>
+regress_aliased_caller_alloc
+regress_annotation_attribute_func
+regress_annotation_custom_destroy
+regress_annotation_get_source_file
+regress_annotation_init
+regress_annotation_invalid_regress_annotation
+regress_annotation_ptr_array
+regress_annotation_return_array
+regress_annotation_return_filename
+regress_annotation_set_source_file
+regress_annotation_space_after_comment_bug631690
+regress_annotation_string_array_length
+regress_annotation_string_zero_terminated
+regress_annotation_string_zero_terminated_out
+regress_annotation_test_parsing_bug630862
+regress_annotation_transfer_floating
+regress_annotation_versioned
+regress_atest_error_quark
+regress_foo_async_ready_callback
+regress_foo_destroy_notify_callback
+regress_foo_enum_type_method
+regress_foo_enum_type_returnv
+regress_foo_error_quark
+regress_foo_init
+regress_foo_interface_static_method
+regress_foo_method_external_references
+regress_foo_not_a_constructor_new
+regress_foo_rectangle_new
+regress_foo_skip_me
+regress_foo_some_variant
+regress_foo_some_variant_ptr
+regress_foo_test_array
+regress_foo_test_const_char_param
+regress_foo_test_const_char_retval
+regress_foo_test_const_struct_param
+regress_foo_test_const_struct_retval
+regress_foo_test_string_array
+regress_foo_test_string_array_with_g
+regress_foo_test_unsigned_qualifier
+regress_foo_test_unsigned_type
+regress_foo_test_varargs_callback
+regress_foo_test_varargs_callback2
+regress_foo_test_varargs_callback3
+regress_func_obj_null_in
+regress_global_get_flags_out
+regress_has_parameter_named_attrs
+regress_introspectable_via_alias
+regress_not_introspectable_via_alias
+regress_random_function_with_skipped_structure
+regress_set_abort_on_error
+regress_test_abc_error_quark
+regress_test_array_callback
+regress_test_array_fixed_out_objects
+regress_test_array_fixed_size_int_in
+regress_test_array_fixed_size_int_out
+regress_test_array_fixed_size_int_return
+regress_test_array_gint16_in
+regress_test_array_gint32_in
+regress_test_array_gint64_in
+regress_test_array_gint8_in
+regress_test_array_gtype_in
+regress_test_array_int_full_out
+regress_test_array_int_in
+regress_test_array_int_inout
+regress_test_array_int_none_out
+regress_test_array_int_null_in
+regress_test_array_int_null_out
+regress_test_array_int_out
+regress_test_async_ready_callback
+regress_test_boolean
+regress_test_boolean_false
+regress_test_boolean_true
+regress_test_cairo_context_full_return
+regress_test_cairo_context_none_in
+regress_test_cairo_surface_full_out
+regress_test_cairo_surface_full_return
+regress_test_cairo_surface_none_in
+regress_test_cairo_surface_none_return
+regress_test_callback
+regress_test_callback_async
+regress_test_callback_destroy_notify
+regress_test_callback_destroy_notify_no_user_data
+regress_test_callback_thaw_async
+regress_test_callback_thaw_notifications
+regress_test_callback_user_data
+regress_test_closure
+regress_test_closure_one_arg
+regress_test_closure_variant
+regress_test_date_in_gvalue
+regress_test_def_error_quark
+regress_test_double
+regress_test_enum_param
+regress_test_error_quark
+regress_test_filename_return
+regress_test_float
+regress_test_garray_container_return
+regress_test_garray_full_return
+regress_test_gerror_callback
+regress_test_ghash_container_return
+regress_test_ghash_everything_return
+regress_test_ghash_gvalue_in
+regress_test_ghash_gvalue_return
+regress_test_ghash_nested_everything_return
+regress_test_ghash_nested_everything_return2
+regress_test_ghash_nothing_in
+regress_test_ghash_nothing_in2
+regress_test_ghash_nothing_return
+regress_test_ghash_nothing_return2
+regress_test_ghash_null_in
+regress_test_ghash_null_out
+regress_test_ghash_null_return
+regress_test_glist_container_return
+regress_test_glist_everything_return
+regress_test_glist_nothing_in
+regress_test_glist_nothing_in2
+regress_test_glist_nothing_return
+regress_test_glist_nothing_return2
+regress_test_glist_null_in
+regress_test_glist_null_out
+regress_test_gslist_container_return
+regress_test_gslist_everything_return
+regress_test_gslist_nothing_in
+regress_test_gslist_nothing_in2
+regress_test_gslist_nothing_return
+regress_test_gslist_nothing_return2
+regress_test_gslist_null_in
+regress_test_gslist_null_out
+regress_test_gtype
+regress_test_gvariant_as
+regress_test_gvariant_asv
+regress_test_gvariant_i
+regress_test_gvariant_s
+regress_test_gvariant_v
+regress_test_hash_table_callback
+regress_test_int
+regress_test_int16
+regress_test_int32
+regress_test_int64
+regress_test_int8
+regress_test_int_out_utf8
+regress_test_int_value_arg
+regress_test_long
+regress_test_multi_callback
+regress_test_multi_double_args
+regress_test_multiline_doc_comments
+regress_test_nested_parameter
+regress_test_null_gerror_callback
+regress_test_owned_gerror_callback
+regress_test_short
+regress_test_simple_boxed_a_const_return
+regress_test_simple_callback
+regress_test_size
+regress_test_skip_unannotated_callback
+regress_test_ssize
+regress_test_struct_a_parse
+regress_test_strv_in
+regress_test_strv_in_gvalue
+regress_test_strv_out
+regress_test_strv_out_c
+regress_test_strv_out_container
+regress_test_strv_outarg
+regress_test_timet
+regress_test_torture_signature_0
+regress_test_torture_signature_1
+regress_test_torture_signature_2
+regress_test_uint
+regress_test_uint16
+regress_test_uint32
+regress_test_uint64
+regress_test_uint8
+regress_test_ulong
+regress_test_unconventional_error_quark
+regress_test_unichar
+regress_test_unsigned_enum_param
+regress_test_ushort
+regress_test_utf8_const_in
+regress_test_utf8_const_return
+regress_test_utf8_inout
+regress_test_utf8_nonconst_return
+regress_test_utf8_null_in
+regress_test_utf8_null_out
+regress_test_utf8_out
+regress_test_utf8_out_nonconst_return
+regress_test_utf8_out_out
+regress_test_value_get_fundamental_object
+regress_test_value_return
+regress_test_value_set_fundamental_object
+regress_test_versioning
+
+<SECTION>
+<FILE>regress-annotation-object</FILE>
+<TITLE>RegressAnnotationObject</TITLE>
+RegressAnnotationObject
+RegressAnnotationObjectClass
+regress_annotation_object_allow_none
+regress_annotation_object_calleeowns
+regress_annotation_object_calleesowns
+regress_annotation_object_compute_sum
+regress_annotation_object_compute_sum_n
+regress_annotation_object_compute_sum_nz
+regress_annotation_object_create_object
+regress_annotation_object_do_not_use
+regress_annotation_object_extra_annos
+regress_annotation_object_foreach
+regress_annotation_object_get_hash
+regress_annotation_object_get_objects
+regress_annotation_object_get_strings
+regress_annotation_object_hidden_self
+regress_annotation_object_in
+regress_annotation_object_inout
+regress_annotation_object_inout2
+regress_annotation_object_inout3
+regress_annotation_object_method
+regress_annotation_object_notrans
+regress_annotation_object_out
+regress_annotation_object_parse_args
+regress_annotation_object_set_data
+regress_annotation_object_set_data2
+regress_annotation_object_set_data3
+regress_annotation_object_string_out
+regress_annotation_object_use_buffer
+regress_annotation_object_watch
+regress_annotation_object_watch_full
+regress_annotation_object_with_voidp
+
+<SECTION>
+<FILE>regress-foo-buffer</FILE>
+<TITLE>RegressFooBuffer</TITLE>
+RegressFooBuffer
+RegressFooBufferClass
+regress_foo_buffer_some_method
+
+<SECTION>
+<FILE>regress-foo-interface</FILE>
+<TITLE>RegressFooInterface</TITLE>
+RegressFooInterface
+RegressFooInterfaceIface
+regress_foo_interface_do_regress_foo
+regress_foo_interface_static_method
+
+<SECTION>
+<FILE>regress-foo-object</FILE>
+<TITLE>RegressFooObject</TITLE>
+RegressFooObject
+RegressFooObjectClass
+regress_foo_object_append_new_stack_layer
+regress_foo_object_dup_name
+regress_foo_object_external_type
+regress_foo_object_get_name
+regress_foo_object_handle_glyph
+regress_foo_object_is_it_time_yet
+regress_foo_object_new_cookie
+regress_foo_object_read
+regress_foo_object_skipped_method
+regress_foo_object_take_all
+regress_foo_object_various
+regress_foo_object_virtual_method
+regress_foo_object_a_global_method
+regress_foo_object_get_default
+regress_foo_object_static_meth
+
+<SECTION>
+<FILE>regress-foo-other-object</FILE>
+<TITLE>RegressFooOtherObject</TITLE>
+RegressFooOtherObject
+RegressFooOtherObjectClass
+
+<SECTION>
+<FILE>regress-foo-sub-interface</FILE>
+<TITLE>RegressFooSubInterface</TITLE>
+RegressFooSubInterface
+RegressFooSubInterfaceIface
+regress_foo_sub_interface_do_bar
+regress_foo_sub_interface_do_baz
+
+<SECTION>
+<FILE>regress-foo-subobject</FILE>
+<TITLE>RegressFooSubobject</TITLE>
+RegressFooSubobject
+RegressFooSubobjectClass
+
+<SECTION>
+<FILE>regress-test-floating</FILE>
+<TITLE>RegressTestFloating</TITLE>
+RegressTestFloating
+RegressTestFloatingClass
+
+<SECTION>
+<FILE>regress-test-fundamental-object</FILE>
+<TITLE>RegressTestFundamentalObject</TITLE>
+RegressTestFundamentalObject
+RegressTestFundamentalObjectClass
+regress_test_fundamental_object_ref
+regress_test_fundamental_object_unref
+
+<SECTION>
+<FILE>regress-test-fundamental-sub-object</FILE>
+<TITLE>RegressTestFundamentalSubObject</TITLE>
+RegressTestFundamentalSubObject
+RegressTestFundamentalSubObjectClass
+
+<SECTION>
+<FILE>regress-test-inherit-drawable</FILE>
+<TITLE>RegressTestInheritDrawable</TITLE>
+RegressTestInheritDrawable
+RegressTestInheritDrawableClass
+regress_test_inherit_drawable_do_foo
+regress_test_inherit_drawable_do_foo_maybe_throw
+regress_test_inherit_drawable_get_origin
+regress_test_inherit_drawable_get_size
+
+<SECTION>
+<FILE>regress-test-interface</FILE>
+<TITLE>RegressTestInterface</TITLE>
+RegressTestInterface
+RegressTestInterfaceIface
+
+<SECTION>
+<FILE>regress-test-obj</FILE>
+<TITLE>RegressTestObj</TITLE>
+RegressTestObj
+RegressTestObjClass
+regress_test_obj_do_matrix
+regress_test_obj_emit_sig_with_foreign_struct
+regress_test_obj_emit_sig_with_int64
+regress_test_obj_emit_sig_with_obj
+regress_test_obj_emit_sig_with_uint64
+regress_forced_method
+regress_test_obj_instance_method
+regress_test_obj_instance_method_callback
+regress_test_obj_set_bare
+regress_test_obj_skip_inout_param
+regress_test_obj_skip_out_param
+regress_test_obj_skip_param
+regress_test_obj_skip_return_val
+regress_test_obj_skip_return_val_no_out
+regress_test_obj_torture_signature_0
+regress_test_obj_torture_signature_1
+regress_test_obj_null_out
+regress_test_obj_static_method
+regress_test_obj_static_method_callback
+
+<SECTION>
+<FILE>regress-test-sub-obj</FILE>
+<TITLE>RegressTestSubObj</TITLE>
+RegressTestSubObj
+RegressTestSubObjClass
+regress_test_sub_obj_instance_method
+regress_test_sub_obj_unset_bare
+
+<SECTION>
+<FILE>regress-test-wi8021x</FILE>
+<TITLE>RegressTestWi8021x</TITLE>
+RegressTestWi8021x
+RegressTestWi8021xClass
+regress_test_wi_802_1x_get_testbool
+regress_test_wi_802_1x_set_testbool
+regress_test_wi_802_1x_static_method