From 6a6b83635f68883b422b2fe695316bbac876bcd3 Mon Sep 17 00:00:00 2001 From: Aparajita Fishman Date: Wed, 18 May 2011 07:49:52 -0700 Subject: [PATCH] More documentation enhancements... - Changed to centered, fixed-width layout, it results in shorter line lengths which reads more easily. - Moved support files to separate support directory. - Removed blank lines at end of multi-parameter method prototypes. --- Tools/Documentation/doxygen.css | 77 +++++++++++++------ .../postprocess/001.cleanup_headers.sh | 2 +- .../postprocess/002.transform_text.sh | 15 +--- .../preprocess/001.markdown_readme.sh | 2 +- .../preprocess/002.make_headers.sh | 2 +- Tools/Documentation/support/massage_text.py | 40 ++++++++++ .../{ => support}/processor_setup.sh | 0 7 files changed, 99 insertions(+), 39 deletions(-) create mode 100755 Tools/Documentation/support/massage_text.py rename Tools/Documentation/{ => support}/processor_setup.sh (100%) diff --git a/Tools/Documentation/doxygen.css b/Tools/Documentation/doxygen.css index 0f21f5d0b..4c7c19801 100644 --- a/Tools/Documentation/doxygen.css +++ b/Tools/Documentation/doxygen.css @@ -6,7 +6,7 @@ body, table, td, div, p, dl, dd, dt, em { } body, table, div, p { - font: 13px normal "Lucida Grande", Helvetica, Arial, Geneva, sans-serif; + font: normal 13px "Lucida Grande", Helvetica, Arial, Geneva, sans-serif; } table { @@ -18,7 +18,7 @@ pre, code { } p { - margin: 1em 0; + margin: 0 0 1em 0; } dl { @@ -47,7 +47,7 @@ em { h1, h2, h3, h4 { font-family: "Lucida Grande", Helvetica, Arial, Geneva, sans-serif; - margin: 2em 0 1em 0; + margin: 1.5em 0 .5em; } h1 { @@ -109,17 +109,15 @@ div.qindex, div.navtab { background-color: #ECEFF6; border: 1px solid #A4B5D6; text-align: center; - margin: 2px; - padding: 2px; + padding: .25em; } div.qindex, div.navpath { - width: 100%; line-height: 140%; } -div.qindex+table { - margin: 1.5em; +div.contents div.qindex+table { + margin: 1.5em 15px; } div.qindex+table td { @@ -238,12 +236,32 @@ body { } div.contents { - margin: 1.5em; + width: 1024px; + margin: auto; + border: 1px solid #eee; + border-width: 0 1px; + padding: 15px; } /* If the first element of the contents is a table, give it some space */ div.contents > table { - margin-top: 1.5em; + margin: 1.5em 0 0; +} + +div.contents > p, +div.contents > h1, +div.contents > h2, +div.contents > dl, +.dynheader, +.dynsummary, +.dyncontent { + padding-left: 0; + padding-right: 0; +} + +div.contents hr { + margin-left: -15px; + margin-right: -15px; } td.indexkey { @@ -262,10 +280,6 @@ td.indexvalue { padding: .25em 0 .25em .5em; } -table tr.memlist:first-child td { - padding-top: 1.5em; -} - table tr.memlist > td { padding-left: .5em; } @@ -405,6 +419,7 @@ hr { hr.footer { height: 1px; + margin-top: 0; } /* @group Member Descriptions */ @@ -413,6 +428,7 @@ table.memberdecls { font-family: Consolas, "Lucida Console"; border-spacing: 0px; padding: 0px; + margin: 0 !important; } .mdescLeft, .mdescRight, @@ -470,13 +486,13 @@ table.memberdecls { .memname { white-space: nowrap; font: bold 105% Consolas, "Lucida Console"; - margin: .25em 0 0 .25em; + margin: .25em 0 .1em .25em; } .memproto { - margin-top: 2em; + margin: 2em -15px 0; border-top: 1px solid #ccc; - padding: 6px 0px 6px 0px; + padding: 6px 15px; color: #253554; background-color: #f7f7f7; font-family: Consolas, "Lucida Console"; @@ -484,7 +500,8 @@ table.memberdecls { } .memdoc { - padding: .5em .5em 0; + margin: 0 -15px; + padding: .5em 15px 0; } .memdoc > p { @@ -493,6 +510,11 @@ table.memberdecls { .memdoc dl dd td { padding-right: 1em; + padding-top: .5em; +} + +.memdoc dl dd table tr:first-child td { + padding-top: 0; } .memdoc dl dd table tr td:first-child { @@ -621,7 +643,15 @@ table.memberdecls { /* @end */ div.dynheader { - margin-top: 8px; + margin-top: 8px; +} + +div.dynheader.closed { + margin-bottom: 1em; +} + +div.dyncontent { + margin-bottom: 1em; } address { @@ -700,7 +730,6 @@ div.summary { float: right; font-size: 90%; - padding-right: 5px; width: 50%; text-align: right; } @@ -715,9 +744,12 @@ div.header background-image:url('nav_h.png'); background-repeat:repeat-x; background-color: #F9FAFC; - margin: 0; - padding: 1.5em; + width: 1024px; + margin: 0 auto; + padding: 1.5em 15px; border-bottom: 1px solid #C5CFE5; + border-left: 1px solid #eee; + border-right: 1px solid #eee; } div.headertitle h1 { @@ -728,7 +760,6 @@ div.headertitle h1 { .tabs, .tabs2, .tabs3 { background-image: url('tab_b.png'); - width: 100%; z-index: 101; font-size: 100%; } diff --git a/Tools/Documentation/postprocess/001.cleanup_headers.sh b/Tools/Documentation/postprocess/001.cleanup_headers.sh index bbb23414c..bd271367b 100755 --- a/Tools/Documentation/postprocess/001.cleanup_headers.sh +++ b/Tools/Documentation/postprocess/001.cleanup_headers.sh @@ -6,7 +6,7 @@ # $2 Generated documentation directory # Do this if you want to use the utility functions -source "$1"/processor_setup.sh +source "$1"/support/processor_setup.sh # Cleanup the files we generated to feed to doxygen processor_msg "Cleaning up generated header files..." diff --git a/Tools/Documentation/postprocess/002.transform_text.sh b/Tools/Documentation/postprocess/002.transform_text.sh index 3b116a3d8..3cd354752 100755 --- a/Tools/Documentation/postprocess/002.transform_text.sh +++ b/Tools/Documentation/postprocess/002.transform_text.sh @@ -6,12 +6,7 @@ # $2 Generated documentation directory # Do this if you want to use the utility functions -source "$1"/processor_setup.sh - -# The following transforms are performed: -# - Strip useless "[implementation]" littering the docs -# - Change "Static Public Member Functions" to "Class Methods" -# - Change "Public Member Functions" to "Instance Methods" +source "$1"/support/processor_setup.sh if [ ! -d "$2" ]; then exit 0 @@ -19,10 +14,4 @@ fi processor_msg 'Massaging text...' -sed -i '' -E \ --e 's/ \[implementation\]<\/code>/\ /g' \ --e 's/Static Public Member Functions/Class Methods/g' \ --e 's/Public Member Functions/Instance Methods/g' \ --e 's/Member Function Documentation/Method Documentation/g' \ --e 's/(AppKit|Foundation)\.doc/\1/g' \ -"$2"/*.html +exec "$1"/support/massage_text.py "$2" diff --git a/Tools/Documentation/preprocess/001.markdown_readme.sh b/Tools/Documentation/preprocess/001.markdown_readme.sh index 72a040eff..8f23e4ef4 100755 --- a/Tools/Documentation/preprocess/001.markdown_readme.sh +++ b/Tools/Documentation/preprocess/001.markdown_readme.sh @@ -5,7 +5,7 @@ # $1 Cappuccino documentation directory # Do this if you want to use the utility functions -source "$1"/processor_setup.sh +source "$1"/support/processor_setup.sh markdown=`which markdown` diff --git a/Tools/Documentation/preprocess/002.make_headers.sh b/Tools/Documentation/preprocess/002.make_headers.sh index f4e43fef3..72c1dfba0 100755 --- a/Tools/Documentation/preprocess/002.make_headers.sh +++ b/Tools/Documentation/preprocess/002.make_headers.sh @@ -5,7 +5,7 @@ # $1 Cappuccino documentation directory # Do this if you want to use the utility functions -source "$1"/processor_setup.sh +source "$1"/support/processor_setup.sh if [ -d AppKit.doc ]; then rm -rf AppKit.doc diff --git a/Tools/Documentation/support/massage_text.py b/Tools/Documentation/support/massage_text.py new file mode 100755 index 000000000..aa82fb8c0 --- /dev/null +++ b/Tools/Documentation/support/massage_text.py @@ -0,0 +1,40 @@ +#!/usr/bin/env python +# +# $1 Generated documentation directory + +# The following transforms are performed: +# - Strip useless "[implementation]" littering the docs +# - Change "Static Public Member Functions" to "Class Methods" +# - Change "Public Member Functions" to "Instance Methods" +# - Change "Member Function Documentation" to "Method Documentation" +# - Remove empty line left at the end of multi-parameter method prototypes + +import glob +import os.path +import re +import sys + +transforms = [ + re.compile(r" \[implementation\]"), " ", + re.compile(r"Static Public Member Functions"), "Class Methods", + re.compile(r"Public Member Functions"), "Instance Methods", + re.compile(r"Member Function Documentation"), "Method Documentation", + re.compile(r"(AppKit|Foundation)\.doc"), r"\1", + re.compile(r"\s*\n(\s*\n){2}\s*(){2} \n\s*"), "" +] + +html = glob.glob(os.path.join(sys.argv[1], "*.html")) + +for count, filename in enumerate(html): + f = open(filename, "r+") + text = f.read() + i = 0 + + while i < len(transforms): + text = transforms[i].sub(transforms[i + 1], text) + i += 2 + + f.seek(0) + f.truncate() + f.write(text) + f.close() diff --git a/Tools/Documentation/processor_setup.sh b/Tools/Documentation/support/processor_setup.sh similarity index 100% rename from Tools/Documentation/processor_setup.sh rename to Tools/Documentation/support/processor_setup.sh