add a doxygen code documentation

[aoloe]

at some time we should add a doxygen html documentation of the scribus source code.

[OceanWolf]

I think I know how to do this... basically the process works like this:

1. Switch to the branch/revision we want to document.
2. Run doxygen and put the source in this repo.
3. Commit and push to this repo.

In terms of automation, I think we can only go as far as putting all of the above in a single script file, with a parameter file to control the destination folder of the source, i.e. where we keep this repo on our own computer. The problems for further automation come from:

1. Control of when we update the source. We don't want to do it on every PR that gets accepted for example. Perhaps only when a new version of scribus gets released... so we start with a 1.5 version of the documentation.
2. I don't see a way to do any auto-update at the moment. It all looks static.

[OceanWolf]

Okay, an updated version of this... I now know a bit more of what to do here having gone through how matplotlib does it, but first a few questions...

1. The stable documentation... I want to build the doc for 1.5, as this looks like the latest "stable" release, but I don't see a tag for it on the repository... what happened? Should I build 1.4.5 instead?
2. Documentation of what exists currently on master... I can auto-update this with travis as we do in matplotlib, but I need to edit .travis.yml which raises the same question we had in DOC: Changelog and Readme for github. Closes #22 scribus#23, how to keep such commits independent of svn. Do the svn people use travis? Or do we just use this on github?

Almost there, and then we will have our thing working, still a bit more reading to do to finish understanding how github pages work, but almost there... 😄.

[aoloe]

for now github will stay a 100% mirror of the svn repository.

travis is a community effort and is not used by the team. but the team is cooperative, and we got the .travis.yml file into the svn trunk.

if you have reasons to edit it, we will submit the edited version to the trunk! that's not a problem!

the main problem with adding a README_github.md is that it will not be shown as the default readme in any case...
but i'd like to submit the revised README so that it is shown nicer on github.
and mybe get it to be renamed to README.md if needed.
the team is very receptive and if we make good proposals, they mostly get accepted!

[OceanWolf]

Okay, great stuff. Apologies for behaving so conservatively, still finding my feet within the community and understanding the relationships between the two... I presumed that the svn should not contain any github specific stuff, i.e. ``.travis.yml`.

Anyway, that helps clear it up, I will whip up a nicer Github Readme in scribusproject/scribus#23 and get the docs up and running with travis :).

[OceanWolf]

attn: @luzpaz making sure you see this conversation as well.

Just finished a first run of doxygen and it comes to 422Mb from the html, and 111Mb from the latex, but I don't think we need the latex code. My first time running doxygen, so not too sure what we need, but it seems to work. Shall I go ahead and upload it to scribus.io/1.4.5? Then I will get the auto doc of master working with Travis...

[luzpaz]

@OceanWolf sorry I'm busy this weekend. I'm doing some work related training.

re: scribus.io/1.4.5
Sounds good. Green light 👍

[OceanWolf]

Just realised, not much point at doing a 1.4.5, or any specific version, as only those who want to develop the codebase will want to see. The python scripting on the other hand, I would say we would want to catalogue the versions, right?

Or does a stronger connection exist between the C++ and python code making the C++ doc helpful?

[OceanWolf]

bump...

for the docs built from master, we need a new repo, I don't think I have permissions to create it, anyway call it something like devdocs. I can then adjust the .travis.yml to automatically update the documentation when new stuff gets pushed to master.

[luzpaz]

sorry, sort of back from my hiatus. @OceanWolf I'll create a new devdoc repo and give you permissions to it

[luzpaz]

Done, see https://github.com/scribusproject/scribus-devdocs

[OceanWolf]

Ahh thanks, but could you just call it devdocs and not scribus-devdocs?

Basically this repo acts as a subdirectory of scribus.io, so www.scribus.io/devdocs, www.scribus.io/scribus-devdocs looks a bit weird for a url ;).

[OceanWolf]

Renaming looks quite simple... https://help.github.com/articles/renaming-a-repository/

[luzpaz]

@OceanWolf Sorry. Yes, good point. Done

[OceanWolf]

Cool, I will put a PR in on this later... just heading out now.