Readme.md, Contribution.md, .gitignore

[sakulstra]

Can't be merged in like this!

Contribution.md:

• we should create a docs git for sphinx first( didn't want to do without asking )
• should we mention tests at all? there are sth. like no core test cases...
• should we setup travis-ci to check PR's?
• do we follow any named coding standard?

Readme.md:

• is there any mailing list, we want to link to?
• should we mention DIY?

[ncraun]

I'm not opposed to having a sphinx docs repo, as long as it is easy to use/edit/export. I like that the Github wiki is git based so I can just clone the repo, edit the files, commit and push, it's displayed right on Github, and it's easy to backup you can just git clone. But like I said if there's a convenient, easy, way to setup a sphinx wiki, I have no problem with that.

Regarding tests, I think it would be a reasonable policy for any new code to have tests submitted with it, and if you change existing code, make a test case for that too. But for the rest, it's a bit overwhelming to try and test everything at once.

I'm not so sure about the travis-ci for checking pull requests. All the pull requests should be given careful scrutiny by hand anyway before being merged in, and I'm afraid having a little green bar from travis-ci saying everything would work makes it a little too tempting to skip due diligence. But then again, I have not used this tool before and I'm open to suggestions.

Code style should just be whatever the style of the file you're editing is. I don't know if it has a specific stylename, but it should fit in with it's surroundings. Also important is you should turn off any auto-code formatting features of your editor, to produce cleaner diffs that don't have a bunch of distracting reformatting noise.

The README should have links to the home page, Github project page, irc channel, mailing list, forums under a Contact heading. It would also be good to have some GNU style documents, such as CONTRIBUTORS, INSTALL, README, etc in the project dir root, and move all the source code into a separate src/ directory. I also would prefer to keep these as plain text files with a lot of Markdown tags in them, because these files are often examined after downloading with the system text editor which may not have good markdown support. Also a man page would be nice, explaining usage especially for Linux users.

[sakulstra]

i've never used sphinx before, but jbaiter offered to help us with this cause he's using it with http://spreads.readthedocs.org/en/latest/ ...using sphinx will help us to keep the documentation cleaner, easier to maintain and even to implement l10n for the docs(i doubt, that we want this) - sphinx will still be git based and using markdown syntax, but with the possibility to generate some api docs as web interface

so we'll stay with boost test cases? - i'm not experienced in c++ testing.

travis-ci will give the user direct feed back if he/she messed up, but you're right - we have to check anything by hand.

kk i'll try to write this down a bit more formal

don't know if i'll find time for all of this, but i think we can do this later on

[jbaiter]

Migrating the current GitHub wiki to sphinx should be realtively straightforward. The files will continue to be in the repository (most likely in a doc subdirectory) and only have to be converted from Markdown to ReST, which can be done fully automatically.
Then, we can wire up the repository with ReadTheDocs.org, which will build and host up-to-date docs in HTML, PDF and ePub every time changes are made to the documentation source.

[sakulstra]

Sounds good to me!,
I would prefer pushing docu to a different repository(scantailor/docs or sth.), so you don't have to clone everything if you just want to contribute to the docs. I think there are some people who would like to contribute to the docs, but not to the code.

[jbaiter]

You can edit the docs straight through the GitHub web interface, the editor supports ReST syntax as well. So people only have to click the 'fork' button, edit the docs, submit a pull request and are done, no need for cloning the whole source code to their local machine.
And regardless, it's not like ScanTailor has such a huge code base that it takes minutes to clone (like the Linux kernel), so I don't think this is really an issue.

[sakulstra]

It isn't a real issue. I live in a modern country myself, so I don't have to concern about slow downloads :) But I've seen some projects moving there docs outside the main repo in consideration for people living in bad internet country. I personally can't see a disadvantage in moving docs outside the main repo - are there any?, and I don't have a problem with keeping them in the main repo either. Just decide for one and I'll try help fixing links and stuff like that.

[sha101]

I think so...

[sha101]

I trouble with this