[W-I-P] Doxygen

[OceanWolf]

At the moment just want to get travis building the doc, then I will need some help to get travis to upload it to the site (it needs the owners to do some github magic).

[OceanWolf]

I think the build times out due to too many warnings about missing documentation, i.e. it generates a 4Mb log file, mostly filled with these warnings, which travis takes assumes as a bad structure.

I see we have three options here:

1. Make it an accepted fail (for now) and don't upload the docs.
2. Make it an an accepted fail but upload the docs anyway.
3. Do the documentation now (that might take some time)...

[luzpaz]

Apologies. Been super busy and engaged with other responsibilities.
@aoloe opinion?

[aoloe]

/me rather busy, too...
i'd like to see the docs online, yes.
the only concern about putting on the gitbhub page, is that the "simplest" way to add the doxygen output is to add it to the repository... but i don't see the interest in having revisions of the output.
i've tried to google for a solution but did not find any... does anybody know of a good way of doing that?

[OceanWolf]

@aoloe Yes, I will achieve exactly that here as we do the same thing on matplotlib.

To explain how the Travis changes work here:

1. Everytime Travis runs it will test to see if we can build the documentation, if not it will throw an error, if you click through to the travis page you will see three builds, one for each compiler, plus a build that tests the documentation. Note that this does not change the repository as all revisions will get lost.
2. The next step when we have the Travis doc build passing, we checkout the gh-pages branch of devdocs or whatever we call it, and get Travis to remove all the git history (orphan branch) and copy across the Travis generated docs and commit.

My concern with this only lies in how long doxygen will take to run. 35mins to build scribus itself seems long enough, but 50mins+ to build the docs?

[aoloe]

@OceanWolf , i've usd your doxygen file to generate http://impagina.org/dox/

i've only kept the `en/` directoy. i have the feeling there are a few issues: - from `index.html` i can't get to the rest of the content... is there something not 100% correct in the doxygen file or did do something wrong? - the scribus documentation is not (really and completely) free and i'd like to keep it separate from the developer's documentation. it's not maintained anymore in this forum and it has been moved to the wiki (in a part that has not the same license as the rest of the wiki)

personally, it was mostly pleasant to generate the doc and upload it per ftp... i'm not sure that we need a more complex workflow.

but what we need for sure is to get the doxygen file to be commited to the scribus trunk and then work on improving the quality of the doxygen comments and output!

what are your thoughts?

update: i was completely wrong in the strokethrough part, ignore it. new dox/ files have been uploaded.

[OceanWolf]

What do you mean by the "scribus documentation"? Do you mean the stuff in doc/? I don't use any of that...

Erm, I don't see where you have put the doxygen documentation... that looks like just the old documentation.

With the workflow, it really suits two purposes:

1. Checking the documentation for errors. This way we find out quickly if there were problems with documentation (bad doc syntax, etcetera). This I do in this commit, and from the warnings I see both missing doc, and bad syntax with some of the doc (see below for some examples).
2. Auto generation and upload of doc to site when something changes on master. From experience I can see us becoming very lazy with doing this manually (time-consuming and boring, essentially very tedious).

I think we should do two things, upload this (with a change to make this (step-1) an allowed failure for travis; and then we work on the documentation to get that up to par... we will use step-1 to track our progress, in the meantime I will do at least one push of doc to our website.

Does that sound good? If so I will work on that later this week.

scribus/plugins/tools/spellcheck/suggest.h:216: warning: Unsupported xml/html tag <size> found
scribus/plugins/tools/spellcheck/suggest.h:222: warning: argument 'None' of command @param is not found in the argument list of Speller::Aspell::Suggest::printMainList()

[aoloe]

ok, got it, no idea how i could miss the doxygen/ directory.
i've now uploaded the html/ directory to http://impagina/dox.

the steps are:

• cd doc/ && doxygen
• cd doxygen && zip -r dox.zip html
• ftpput ftp.impagina.org dox.zip (well, not exactly this way)
• on the server: unzip dox.zip && mv html dox

not really black magic, but it takes some time to upload all the files.

and i agree about your point about automation.
here the reason why i don't feel it as urgent step: because of the way the scribus community works, there is a risk that when automated workflows break, nobody will be there to fix them. for this reason i tend to prefer well defined workflows to scripts on some server... it's just a priority thing, not more than that.

[OceanWolf]

Lol, I did try to make it obvious 👼.

I get your point about automation workflows, however this works as a catch all workflow tied to github, so whenever something on github changes (however that happens), it will update the docs.