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.



  • Thanks very much for all your valuable help. I've started messing around with includes to see if I can get something positive to happen, and I'll take a look at the qdoc3 source (although much of it will be like Greek to me).

    Thanks again.


Log in to reply
 

Looks like your connection to Qt Forum was lost, please wait while we try to reconnect.