QDoc3 and stylesheets
-
I can't get mine to work. I have a directory containing myconfig.qdocconfig, and I put mystyles.css into the same directory. When I run qdoc3, no stylesheet is applied to the HTML output (in the default html output directory), and mystyles.css does not get copied to html/style.
I'm probably forgetting to set some variable in the config file. Any enlightenment and/or suggestions are appreciated.
-
First hint: you should use doxygen.
HTML.stylesheets = classic.css
There is this kind of thingy, which seems to contol which is the stylesheet used. I haven’t yet managed to successfully reproduce Jambi doc, so I’m just guessing this is how it works. Another way to do that could be adding proper <link> to header section of the page, if there is variable for that.
-
Thanks for the reply. I do like doxygen, but I'm trying to learn QDoc for the hopeful day in the near future when it will extract/process inline comments from QML files.
I forgot to mention in my OP that I have the following entry in myconfig.qdocconfig:
@HTML.stylesheets = mystyles.css@
That doesn't seem to help, though. I also tried:
@HTML.stylesheets = html/style/mystyles.css@
and:
@HTML.stylesheets = ./mystyles.css@
and:
@HTML.stylesheets = ./html/style/mystyles.css@
Thanks again for your reply. Good luck with the Jambi stuff (I'm not working with java at the moment so I'm not much help there).
-
When you have generated the doc, open one generated (full) file.
Between <head> and </head> there should be <link .. /> row. This is the row that adds the stylesheet to the doc. Is the path correct? It is relative to the dir where the html file is, so check if it is correct.
But then again, I’m only guessing how it works...
-
Yes, thanks again. I have checked the generated HTML files, they do not show mystyles.css anywhere in the <head></head> section. The stylesheet links that do get generated include the following:
@<head>
...
<link rel="stylesheet" type="text/css" href="style/style.css" />
<link rel="stylesheet" type="text/css" href="style/superfish.css" />
<link rel="stylesheet" type="text/css" href="style/narrow.css" />
...
</head>@Even those stylesheet files, though, aren't copied to html/style, and no styles appear to be applied to the output at all. I can get styles to work by manually copying a .css file to html/style after the docs have been generated, but that's not going to be much of a solution going forward.
I suppose I could define the HTML.style variable instead, but I hoped to clue in to how the HTML.stylesheets variable works. The myconfig.qdocconf file looks as follows:
@# QDoc is a tool that constantly evolves to suit our needs,
and there are some compatibility issues between old and new
practices. For that reason, any QDoc configuration file needs to
include compat.qdocconf.
include(compat.qdocconf)
The language variable specifies the source code language
being documented.
#language = Qml
The outputdir variable specifies the directory
where QDoc will put the generated documentation.
outputdir = html
The HTML.stylesheets variable specifies the stylesheets used
to define the style of the documentation output.
HTML.stylesheets = mystyles.css
The headerdirs variable specifies the directories
containing the header files associated
with the .cpp source files used in the documentation.
headerdirs = .
The sourcedirs variable specifies the
directories containing the .cpp or .qdoc
files used in the documentation.
sourcedirs = src
The sources.fileextensions variable specifies the
file types that QDoc will read for document generation.
sources.fileextensions += *.qml *.qdoc
The exampledirs variable specifies the directories containing
the source code of the example files.
exampledirs = .
The imagedirs variable specifies the
directories containing the images used in the documentation.
imagedirs = ./images@
I put compat.qdocconf in the same directory as myconfig.qdocconf, just in case there was some compatibility thing causing problems (apparently not).
-
Siting, the manual, “QDoc expects to find stylesheets in the directory containing the qt.qdocconf file, and it will copy those specified to the output directory alongside the HTML pages.”
http://qdoc3.smar.fi/24-qdoc-configuration-htmlvariables.html#html-stylesheets
-
Thanks very much for all your helpful suggestions. I did try copying qt.qdocconf from the qt\tools\qdoc3\test directory of the Qt SDK installation to the directory where I have myconfig.qdocconf and compat.qdocconf. It didn't seem to help, mystyles.css still gets ignored. Am I required instead to copy mystyles.css to some directory of the Qt SDK installation where qdoc3 will recognize it?
Sigh, I miss the doxywizard configuration GUI...
-
To continue from above, I concluded (perhaps erroneously) that qt.qdocconf is used specifically for generation of Qt reference documentation, and shows up in the QDoc manual here & there because that has been the Trolls' singular use of QDoc. Perhaps the manual is in scope now for an update.
-
I suppose this is one of those cases I’d just resort to reading the source (of qdoc3). I’d do it now but it’s too late here for me to do it now... Or just wait trolls answering to this.
You need to include this qt.qdocconf in myconfig.qdocconf in order to get it included.
And, I think you are right, it was just a suggestion to see if it changes anything.