Improve documentation

[tfussell]

Documentation feels a little scattered/unfinished. It should be more focused on how to use the library. Generally:

• Why use xlnt
• License
• What works/doesn't work
• How to get it
• How to compile it
• cmake options
• using system dependencies or git submodules for dependencies
• An example of using xlnt as a static library or dynamic library
• Samples focused on major components organized by category
• Summary of performance benchmarks
• Link to API reference
• How to contribute

[tfussell]

New documentation is now hosted here: https://tfussell.gitbooks.io/xlnt.
It has been requested that samples be added to the documentation which cover: reading and writing tabular data, simple cell formatting, speed benchmarks.

[tpmccallum]

I would like to assist with the documentation.
My interest is in the performance and scalability of xlnt; I am writing C++ code to read and write very large and complex spreadsheets using xlnt exclusively. Some documentation in this area may assist in answering the "Why use xlnt" question.

To date my work is all done on the latest LTS Ubuntu and I am happy to write some documentation on how to install using the latest compilers etc.

I see that there is documentation in readthedocs as well as gitbooks etc. Where would be the best place to contribute to the definitive documentation?

[tfussell]

It's generous of you to offer to help @tpmccallum. I've been trying out various documentation hosting solutions since I started the project and I've recently settled on GitBooks since it's nice and easy for contributors. All you have to do is edit the Markdown files in the docs directory, send in the changes as a pull request, and it will automatically show up here once I merge it in (except docs/api is automatically generated by parsing header files).

I'm also interested to hear about how xlnt performs when handling large files. While I try to write performant code when possible, I'm primarily shooting for accuracy for now. I ported a few of the benchmarks from openpyxl, but they're difficult to realistically compare since the memory model is so different.

[tpmccallum]

Hi @tfussell
Can I get some advice on how you would prefer me to contribute. I figured that sending in changes in the docs folder as a pull request to master was ok. Apologies if you would have preferred any changes to go to another branch instead. The reason I ask is that after I created the pull request I saw some CI test running (as a result).
Just making sure that my contributions are helpful and in line with your workflow.
Kind regards
Tim

[tfussell]

Hi @tpmccallum,

That was a good method. I've been slow to review your pull request since I'm preparing for a trip and trying desperately to squash the last few bugs in the OLE compound document writing code that's on the dev branch. Travis and AppVeyor run automatically after pull requests and commits. Master has a bug that's fixed in the dev branch which is why it's failing. Your pull request was built off of master so it was marked as failing too. I'll merge in my fixes and everything should be back to normal later today.

Cheers,
Thomas

[tpmccallum]

Brilliant, thanks!

[tfussell]

It could always be better, but I'm happy enough with this for now. Will create a new issue after 1.0 release.