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.

[aoloe]

... if the content of the repo is just the result of doxygen, i think it would be better to call it

• code-reference
• code-documentation
  ... personally, i would call it javadoc, but i know it's the wrong name for it :-)

[luzpaz]

What looks/sounds the best?
scribus.io/devdocs
scribus.io/developer-docs
scribus.io/code-reference
scribus.io/code-documentation

[OceanWolf]

Yes, the content will only come from doxygen into a single branch named gh-pages, because this contains several hundred megabytes of docs that will change quite regularly , we don't want to track the changes of this code, so by having it in a separate branch, means the bot can erase all the old history when it makes the updated docs...

Naturally we will link to this from the main scribus.io page, so I don't think the name matters that much...

What about my earlier question regarding python? I.e. would people who write python scripts need to refer to the C++ documentation? I could probably answer this question myself given some time, but still trying to find myself away around at the moment.

Anyway, either way I think I don't like code-reference or code-documentation because we want to make it clear that this doc belongs to that from master, and thus developer only, and not general documentation should regular users stumble across it. If possible I would like to create separate documentation for python applicable for those writing custom python scripts.

[aoloe]

the python documentation should probbly be separated from the one created by doxygen. it's of course possible to create both in one go with doxygen, but i'm not sure it's really a good idea. (basically, i'd prefer the python documentation to be manually edited, since the person who care about scripting python do not have access to the main code so they would have a hard time when proposing changes to the documentation)

[OceanWolf]

Yes, I agree that we should separate them... My question here lies in whether we see enough separation between python and cpp code to achieve a good python documentation... I guess I will have to have a proper nosey ;).

Anyway for now, assuming we can separate the docs satisfactorily. I think that pushes us away from the generic "code" in the name, so I go with one of the first two, devdocs or developer-docs.

[luzpaz]

re: repo name
The nice thing here is we can always refine the name of the repo if the need arises.

re: doxygen vs. python
I say separate them. Hopefully it won't be a headache to do.

[OceanWolf]

For now I have done part 1, the generating the documentation part before the uploading to the repo, over in scribusproject/scribus#25.

[aoloe]

hey
somehow i'm still not happy with the whole setup coming after the doxygen doc is generated.
where it should be:

• putting it on scribus.io means revisioning the changes in the documentation, which looks a bit silly to me. but it's just a "i feel unconfortable" not a stopper
• i don't like the paths proposed above. the best probably being "code-reference". the dev ones are imo wrong, since there is more dev documentation than just the doxygen output. i had a look at what do other projects:
• http://fossies.org is using dox/ and is already including the doxygen output for scribus, gimp, inkscape... (fine to me, even if a bit cryptic) ---> btw, we could just use fossies and simply use a link to them; but i don't understand who they are...
• doxygen exposes a bit too much about the process, but it would be very clear about what it contains

personally, i can offer to upload it to http://impagina.org/dox so we have something browsable and find later a perfect solution... (i can imagine that once it's up, we can get it to be on the http://scribus.net/something domain). i might be pretty easy to get it to update by pushin a button...

[aoloe]

p.s.: ok, i try to create a pull-dox script...