Merge lp:~vanvugt/mir/fix-1304998 into lp:mir

[Daniel van Vugt]

First attempt at shrinking the docs. For me, this reduces the expanded
size from 119M to 65M. And 11M compressed (from 56M). (LP: #1304998)

I've had more ideas on how we might improve this. But none proven. Here's how far I got in London...

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:1545
http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-ci/1326/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-android-trusty-i386-build/1594
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-clang-trusty-amd64-build/1592
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-trusty-touch/1167
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-trusty-amd64-ci/1058
        deb: http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-trusty-amd64-ci/1058/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-trusty-armhf-ci/1063
        deb: http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-trusty-armhf-ci/1063/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-builder-trusty-armhf/1168
        deb: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-builder-trusty-armhf/1168/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-runner-mako/1084
    SUCCESS: http://s-jenkins.ubuntu-ci:8080/job/touch-flash-device/6025

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/mir-team-mir-development-branch-ci/1326/rebuild

review: Approve (continuous-integration)

[Andreas Pokorny (andreas-pokorny)]

Due to the switch to xhtml firefox seems to be checking for matching open </close tags.. and we have an xhtml error in our footer file. There is </hr> missing. Doxygen pastes the footer to every xhtml file. xmllint seems to complain about other errors too..

review: Needs Fixing

[Daniel van Vugt (vanvugt)]

Ah, thanks. I forgot people still use Firefox :)

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:1547
http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-ci/1335/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-android-trusty-i386-build/1605
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-clang-trusty-amd64-build/1603
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-trusty-touch/1178
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-trusty-amd64-ci/1067
        deb: http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-trusty-amd64-ci/1067/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-trusty-armhf-ci/1072
        deb: http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-trusty-armhf-ci/1072/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-builder-trusty-armhf/1179
        deb: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-builder-trusty-armhf/1179/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-runner-mako/1092
    SUCCESS: http://s-jenkins.ubuntu-ci:8080/job/touch-flash-device/6033

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/mir-team-mir-development-branch-ci/1335/rebuild

review: Approve (continuous-integration)

[Alan Griffiths (alan-griffiths)]

@"Keep the old .html extension to avoid confusing Firefox, despite what Doxygen recommends."

Wouldn't it be better to fix doc/footer.html.in?

review: Needs Fixing

[Andreas Pokorny (andreas-pokorny)]

you could also just fix the xml errors :)

review: Approve

[Daniel van Vugt (vanvugt)]

No, footer.html is correct already. If I remove the closing tags then it produces incorrect .html files without any closing "html" or "body".

Also, making that (spurious) change does not resolve all of Firefox's complaints about XML parsing. Only using an "html" extension instead of "xhtml" does.

[Robert Carr (robertcarr)]

119 was a more impressive number of docs but if you insist.

review: Approve

[Kevin DuBois (kdub)]

the size of the doc package is something that's irked me in the past, looks like a good way to reduce the size to me.

review: Approve

[Daniel van Vugt (vanvugt)]

Consider this: Our source code release tarballs are always 800 KB. So really any docs measured in tens of megabytes indicates some real inefficiencies in Doxygen. But we can work on that...

=== modified file 'doc/Doxyfile.in'
--- doc/Doxyfile.in	2014-03-06 06:05:17 +0000
+++ doc/Doxyfile.in	2014-04-15 09:09:19 +0000
@@ -118,7 +118,7 @@
 # Doxygen will generate a detailed section even if there is only a brief
 # description.
 
-ALWAYS_DETAILED_SEC    = YES
+ALWAYS_DETAILED_SEC    = NO
 
 # If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all
 # inherited members of a class in the documentation of that class as if those
@@ -382,7 +382,7 @@
 # defined locally in source files will be included in the documentation.
 # If set to NO only classes defined in header files are included.
 
-EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_CLASSES  = NO
 
 # This flag is only useful for Objective-C code. When set to YES local
 # methods, which are defined in the implementation section but not in
@@ -748,7 +748,7 @@
 # against the file with absolute path, so to exclude all test directories
 # for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = */include/mir_test*
+EXCLUDE_PATTERNS       = */include/test/* */3rd_party/*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -1866,7 +1866,7 @@
 # HTML_FILE_EXTENSION to xhtml in order to make the SVG files
 # visible in IE 9+ (other browsers do not have this requirement).
 
-DOT_IMAGE_FORMAT       = png
+DOT_IMAGE_FORMAT       = svg
 
 # If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to
 # enable generation of interactive SVG images that allow zooming and panning.