diff --git a/NEWS b/NEWS index 7502dc8..aa9d74f 100644 --- a/NEWS +++ b/NEWS @@ -5,8 +5,9 @@ serd (0.30.1) unstable; * Fix colliding blank nodes when parsing TriG * Fix missing parse error messages * Fix parsing TriG graphs with several squashed trailing dots + * Improve documentation - -- David Robillard Sun, 17 Mar 2019 15:16:31 +0100 + -- David Robillard Sat, 30 Mar 2019 12:33:56 +0100 serd (0.30.0) stable; diff --git a/doc/footer.html b/doc/footer.html index 42978af..0dc6919 100644 --- a/doc/footer.html +++ b/doc/footer.html @@ -5,14 +5,16 @@ - + diff --git a/doc/header.html b/doc/header.html index f21baf7..2e419e3 100644 --- a/doc/header.html +++ b/doc/header.html @@ -1,52 +1,37 @@ - - + - - - - -$projectname: $title -$title -$treeview -$search -$mathjax - -$extrastylesheet - - -
+ + + $projectname: $title + $title + + $extrastylesheet + + +
- -
- - - - - - - - - - - - - - - - - - - - - -
-
$projectname -  $projectnumber -
-
$projectbrief
-
-
$projectbrief
-
$searchbox
-
- - + +
+ +
+ + diff --git a/doc/layout.xml b/doc/layout.xml index 74a109f..3eed79f 100644 --- a/doc/layout.xml +++ b/doc/layout.xml @@ -1,4 +1,5 @@ + @@ -8,17 +9,31 @@ + + + + + - + + + + + + + + + + - + @@ -27,10 +42,11 @@ - + + @@ -65,6 +81,8 @@ + + @@ -72,6 +90,7 @@ + @@ -81,8 +100,14 @@ + + + + + + @@ -92,6 +117,8 @@ + + @@ -107,10 +134,16 @@ + + + + + + @@ -121,6 +154,8 @@ + + @@ -130,9 +165,9 @@ - - + + @@ -141,6 +176,8 @@ + + @@ -159,6 +196,8 @@ + + diff --git a/doc/reference.doxygen.in b/doc/reference.doxygen.in index e82b120..8e11f86 100644 --- a/doc/reference.doxygen.in +++ b/doc/reference.doxygen.in @@ -44,7 +44,7 @@ PROJECT_NUMBER = @SERD_VERSION@ # for a project that appears at the top of each page and should give viewer a # quick idea about the purpose of the project. Keep the description short. -PROJECT_BRIEF = +PROJECT_BRIEF = "A lightweight library for RDF storage and serialisation" # With the PROJECT_LOGO tag one can specify a logo or an icon that is included # in the documentation. The maximum height of the logo should not exceed 55 @@ -803,7 +803,8 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = @SERD_SRCDIR@/serd/serd.h +INPUT = @SERD_SRCDIR@/serd/serd.h \ + @SERD_SRCDIR@/doc/mainpage.md # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -952,7 +953,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -USE_MDFILE_AS_MAINPAGE = +USE_MDFILE_AS_MAINPAGE = @SERD_SRCDIR@/doc/mainpage.md #--------------------------------------------------------------------------- # Configuration options related to source browsing @@ -984,7 +985,7 @@ STRIP_CODE_COMMENTS = YES # entity all documented functions referencing it will be listed. # The default value is: NO. -REFERENCED_BY_RELATION = YES +REFERENCED_BY_RELATION = NO # If the REFERENCES_RELATION tag is set to YES then for each documented function # all documented entities called/used by that function will be listed. @@ -1008,7 +1009,7 @@ REFERENCES_LINK_SOURCE = YES # The default value is: YES. # This tag requires that the tag SOURCE_BROWSER is set to YES. -SOURCE_TOOLTIPS = YES +SOURCE_TOOLTIPS = NO # If the USE_HTAGS tag is set to YES then the references to source code will # point to the HTML generated by the htags(1) tool instead of doxygen built-in @@ -1203,7 +1204,7 @@ HTML_TIMESTAMP = NO # The default value is: YES. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_DYNAMIC_MENUS = YES +HTML_DYNAMIC_MENUS = NO # If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML # documentation will contain sections that can be hidden and shown after the @@ -1423,7 +1424,7 @@ ECLIPSE_DOC_ID = org.doxygen.Project # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -DISABLE_INDEX = YES +DISABLE_INDEX = NO # The GENERATE_TREEVIEW tag is used to specify whether a tree-like index # structure should be generated to display hierarchical information. If the tag diff --git a/doc/style.css b/doc/style.css index 8420d29..52fdc05 100644 --- a/doc/style.css +++ b/doc/style.css @@ -1,68 +1,113 @@ body { - max-width: 80em; - margin: 0; + background: #FFF; + color: #222; + font-style: normal; + line-height: 1.6em; margin-left: auto; margin-right: auto; - background: #FFF; - color: #000; + padding: 1em; + max-width: 60em; + font-family: "DejaVu Serif",Palatino,serif; + text-rendering: optimizeLegibility; } -#titlearea { - display: none; +h1, .title, #projectname, h2, h3, h4, h5, h6 { + line-height: 1.0125em; + color: #444; + font-family: "DejaVu Sans",Helvetica,Arial,sans-serif; + margin: 1em 0 0.5em 0; +} + +h1, .titlearea .header .titlebox, #projectname { + font-size: 300%; + font-weight: 400; + margin-bottom: 0.25em; + margin-top: 0; } -h1 { +.header .headertitle .title { font-size: 180%; - font-weight: 900; + font-weight: 400; + margin: 0.75em 0.25em 0.5em 0; } -h2 { - font-size: 140%; - font-weight: 700; +.ingroups { + display: inline; +} +.title .ingroups a { + font-size: small; + margin-left: 1em; } -h3 { - font-size: 120%; - font-weight: 700; +#titlebox, #metabox { + display: inline-block; +} +#titlebox{ + display: inline-block; + width: 75%; + left: 0; + top: 0; } -h4 { - font-size: 110%; - font-weight: 700; +#title { + margin-bottom: 0.25em; } -h5 { - font-size: 100%; - font-weight: 700; +#shortdesc { + margin: 0; + color: #666; + display: inline-block; + font-style: italic; + padding: 0; } -h6 { - font-size: 100%; - font-weight: 600; +#titlearea { + margin: 0.25em auto 0.25em auto; + padding: 0; + position: relative; + clear: both; + line-height: 1.0em; } -p { - margin: 0 0 1em 0; +h2 { + font-size: 160%; + font-weight: 400; } -dt { - font-weight: 700; +h3 { + font-size: 140%; + font-weight: 400; } -p.startli,p.startdd,p.starttd { - margin-top: 2px; +h4 { + font-size: 120%; + font-weight: 500; } -p.endli { - margin-bottom: 0; +h5, h6 { + font-size: 110%; + font-weight: 600; +} + +h1 a, h1 a:link, h1 a:visited , +h2 a, h2 a:link, h2 a:visited , +h3 a, h3 a:link, h3 a:visited , +h4 a, h4 a:link, h4 a:visited , +h5 a, h5 a:link, h5 a:visited , +h6 a, h6 a:link, h6 a:visited { + color: #444; } -p.enddd { - margin-bottom: 4px; +p { + margin: 0.5em 0 0.5em 0; +} + +dt { + font-weight: 700; } -p.endtd { - margin-bottom: 2px; +dd { + margin-left: 2em; } caption { @@ -115,30 +160,20 @@ code { color: #444; } -a.code { - color: #4665A2; -} - -a.codeRef { - color: #4665A2; -} - /* @end */ dl.el { margin-left: -1cm; } .fragment { - font-family: monospace, fixed; + font-family: "DejaVu Sans Mono",monospace,fixed; } pre.fragment { border: 1px solid #C4C4C4; background-color: #F9F9F9; - padding: 4px 6px; - margin: 4px 8px 4px 2px; + padding: 0.5em; overflow: auto; - line-height: 125%; } div.ah { @@ -167,10 +202,11 @@ div.groupText { font-style: italic; } -div.contents { - margin-top: 10px; - margin-left: 10px; - margin-right: 10px; +div.contents, #content { + padding: 0 0.25em 0 0.25em; + max-width: 60em; + margin-left: auto; + margin-right: auto; } td.indexkey { @@ -189,7 +225,7 @@ td.indexvalue { } table.memname { - padding-bottom: 1ex; + font-family: "DejaVu Sans Mono",monospace,fixed; } tr.memlist { @@ -217,7 +253,6 @@ div.center img { address.footer { text-align: right; - padding-right: 12px; } img.footer { @@ -227,43 +262,31 @@ img.footer { /* @group Code Colorization */ span.keyword { - color: green; + color: #586E75; } span.keywordtype { - color: #3E873E; + color: #546E00; } span.keywordflow { - color: #e08000; + color: #586E75; } span.comment { - color: maroon; + color: #6C71C4; } span.preprocessor { - color: #806020; + color: #D33682; } span.stringliteral { - color: #002080; + color: #CB4B16; } span.charliteral { - color: teal; -} - -span.vhdldigit { - color: #F0F; -} - -span.vhdlkeyword { - color: #700070; -} - -span.vhdllogic { - color: red; + color: #CB4B16; } /* @end */ @@ -289,17 +312,20 @@ hr { margin: 2em 0 1em; } -hr.footer { - height: 1px; +#footer { + bottom: 0; + clear: both; + font-size: x-small; + margin: 2em 0 0; + padding: 0 1em 1em 1em; + vertical-align: top; + color: #888; } /* @group Member Descriptions */ table.memberdecls { border-spacing: 0.125em; -} - -h2.groupheader { - margin: 0.5em 0 0.25em 0; + line-height: 1.3em; } .mdescLeft,.mdescRight,.memItemLeft,.memItemRight,.memTemplItemLeft,.memTemplItemRight,.memTemplParams { @@ -313,7 +339,7 @@ h2.groupheader { .memItemLeft,.memItemRight,.memTemplParams { border: 0; - font-family: monospace, fixed; + font-family: "DejaVu Sans Mono",monospace,fixed; } .memItemLeft,.memTemplItemLeft { @@ -338,7 +364,7 @@ td.memSeparator { td.mlabels-right { vertical-align: top; padding-top: 4px; - color: #AA6; + color: #B4C342; } .memtitle { @@ -349,13 +375,15 @@ td.mlabels-right { /* @group Member Details */ /* Styles for detailed member documentation */ .memtemplate { - color: #4665A2; - font-weight: bold; + color: #888; + font-style: italic; + font-family: "DejaVu Sans Mono",monospace,fixed; + font-size: small; } .memnav { - background-color: #EBEFF6; - border: 1px solid #A3B4D7; + background-color: #EEE; + border: 1px solid #B4C342; text-align: center; margin: 2px; margin-right: 15px; @@ -363,25 +391,25 @@ td.mlabels-right { } .memitem { - padding: 0.5em; - margin: 1em 0 1em 0; - border: 1px solid #DDD; + padding: 0.25em 0.5em 0.25em 0.5em; + margin: 0 0 1em 0; border-radius: 6px; + border: 1px solid #DDD; } .memproto { - padding: 0; - font-weight: bold; - color: #000; + font-size: 110%; + font-weight: 400; + line-height: 1em; + color: #000; } .memproto .paramname { - color: #444; font-style: normal; } .memdoc { - padding: 0 0 0 2em; + padding: 0 0.25em 0 0.25em; } .paramkey { @@ -389,36 +417,54 @@ td.mlabels-right { } .paramtype { - color: #3E873E; + color: #666; + padding-right: 0.5em; white-space: nowrap; } .paramname { - color: #444; + color: #111; white-space: nowrap; - font-weight: bold; - padding-left: 0.5em; + font-family: "DejaVu Sans Mono",monospace,fixed; + font-style: italic; + padding-right: 0.5em; } .fieldname { color: #000; } +.fieldtable { + padding-top: 0.25em; + border-top: 1px dashed #DDD; +} + +.fieldtable tbody tr:first-child { + display: none; +} + td.fieldname { - padding-right: 0.5em; - padding-left: 2em; + padding: 0 0.5em 0 0.25em; vertical-align: top; + font-family: "DejaVu Sans Mono",monospace,fixed; } td.fieldtype { - color: #444; - padding-right: 0.5em; - padding-left: 2em; + color: #666; + padding: 0 0.5em 0 0; vertical-align: top; + font-family: "DejaVu Sans Mono",monospace,fixed; } td.fielddoc p { margin: 0; + vertical-align: top; + padding: 0 0.5em 0 0; +} + +p.reference { + font-size: x-small; + font-style: italic; } /* @end */ @@ -459,6 +505,22 @@ td.fielddoc p { vertical-align: -30%; } +td.entry { + font-family: "DejaVu Sans",Helvetica,Arial,sans-serif; + font-weight: 400; + padding-right: 1em; +} + +td.entry .arrow { + display: none; +} + +td.entry b { + font-family: "DejaVu Sans",Helvetica,Arial,sans-serif; + font-weight: 400; + font-size: 130%; +} + /* these are for tree view when not used as main index */ .directory-alt { font-size: 100%; @@ -496,7 +558,7 @@ div.dynheader { address { font-style: normal; - color: #2A3D61; + color: #444; } table.doxtable { @@ -528,23 +590,20 @@ table.doxtable th { } div.navpath { - padding: 0.25em; + color: #DDD; } .navpath ul { - font-size: x-small; - color: #8AA0CC; overflow: hidden; margin: 0; padding: 0; } .navpath li { - list-style-type: none; float: left; - padding-left: 10px; - padding-right: 15px; - color: #364D7C; + padding-left: 0; + margin-left: 0.5em; + padding-right: 1em; } .navpath a { @@ -553,62 +612,68 @@ div.navpath { outline: none; } -.navpath a:hover { - color: #6884BD; -} - div.summary { - float: right; - font-size: x-small; - padding: 0.25em 0.5em 0 0; - width: 50%; - text-align: right; + font-size: small; + font-family: "DejaVu Sans",Helvetica,Arial,sans-serif; + margin: 0; + color: #FFF; /* Hide separator bars */ + border-bottom: 1px solid #DDD; + padding: 0.25em 0; } div.summary a { white-space: nowrap; } -div.header { - background-color: #F3F3F3; - margin: 0; +/* Metadata box (right aligned next to title) */ + +#metabox { + display: inline-block; + font-size: x-small; + margin: 0 0 0.25em 0; + position: absolute; + right: 0; + top: 0; + color: #666; + font-style: italic; + padding: 0 1em; +} + +#meta { + border-style: hidden; + margin-right: 0.25em; +} + +#meta tr, #meta th, #meta td { + background-color: transparent; border: 0; + margin: 0; + font-weight: normal; } -div.headertitle { - font-size: 180%; - font-weight: bold; - color: #FFF; - padding: 0.125em 0.25em 0.125em 0.25em; - background-color: #333; - background: linear-gradient(to bottom, #333 0%, #111 100%); - border: solid 1px #444; - border-top: 0; - border-radius: 0 0 6px 6px; +#meta th { + text-align: right; +} + +#meta th:after { + content: ":"; } div.line { - font-family: monospace, fixed; - font-size: 13px; - min-height: 13px; - line-height: 1.0; - text-wrap: avoid; + font-family: "DejaVu Sans Mono",monospace,fixed; + line-height: 1.4em; white-space: pre-wrap; - text-indent: -53px; - padding-left: 53px; - padding-bottom: 0; - margin: 0; } .glow { - background-color: cyan; - box-shadow: 0 0 10px cyan; + background-color: #2AA198; + box-shadow: 0 0 10px #2AA198; } span.lineno { padding-right: 4px; text-align: right; - border-right: 2px solid #0F0; + border-right: 2px solid #546E00; background-color: #E8E8E8; white-space: pre; } @@ -621,22 +686,17 @@ span.lineno a:hover { } .tabs, .tabs2, .navpath { - background-image: none; - background-color: #333; - background: linear-gradient(to bottom, #333 0%, #111 100%); - border: 0; - border-bottom: solid 2px #000; - padding: 0; - padding-top: 2px; - font-size: small; -} - -#navrow1 { - border: 0; + padding: 0.25em 0; + border-bottom: 1px solid #DDD; + font-size: small; + font-family: "DejaVu Sans",Helvetica,Arial,sans-serif; + margin: 0; } th { text-align: left; + font-size: 110%; + font-weight: 500; } .mlabel { @@ -655,40 +715,23 @@ th { display: table-cell; line-height: 2em; list-style: none; - background-color: #333; - background: linear-gradient(to bottom, #444 0%, #222 100%); - border: 1px solid #222; border-bottom: 0; - border-radius: 6px 6px 0 0; - color: #DDD; } .tablist a { display: block; - padding: 0 20px; - font-weight: bold; - color: #859900; + padding: 0 1em 0 0; + font-family: "DejaVu Sans",Helvetica,Arial,sans-serif; text-decoration: none; outline: none; } -.header a { - color: #859900; -} - .tabs3 .tablist a { padding: 0 10px; } -.tablist a:hover { - color: #fff; - text-shadow: 0 1px 1px rgba(0, 0, 0, 1.0); - text-decoration: none; -} - .tablist li.current a { - color: #fff; - text-shadow: 0 1px 1px rgba(0, 0, 0, 1.0); + color: #222; } span.icon { diff --git a/wscript b/wscript index b3bb25f..0387ce7 100644 --- a/wscript +++ b/wscript @@ -167,8 +167,6 @@ def build(bld): bld.install_files('${MANDIR}/man1', 'doc/serdi.1') bld.add_post_fun(autowaf.run_ldconfig) - if bld.env.DOCS: - bld.add_post_fun(lambda ctx: autowaf.make_simple_dox(APPNAME)) def lint(ctx): "checks code for style issues"