Google Season of Docs 2019 Project Ideas List
Xapian is an Open Source Search Engine Library. It's written in C++, with bindings to allow use from many other programming languages.
Our source code is maintained using the git version control system.
We're applying to participate in the 2019 Season of Docs.
You can contact us via IRC on #xapian on irc.libera.chat or on the xapian-devel mailing list. Communication is an important part of open source development and of GSoD - if we haven't talked to you then your application is unlikely to be seriously considered.
Each idea below lists people who have expressed an interest in mentoring it.
Please don't contact individual potential mentors privately - use the IRC channel or the mailing list instead. One reason is that you'll likely get a faster response as other people may be able to help with many questions. Also interacting with the community is an important part of open source development, and we'll be looking for evidence of positive interactions when reviewing applications, but we can't easily take account of private interactions when doing this. The mentor names against each project are only an indication of who might want to mentor it - other people who haven't signed up yet may be interested too.
Project Ideas List
Note that these are ideas - some are more fully formed than others, but don't be afraid to take them and extend or adapt them in your proposal to produce something you're more interesting in working on. If you think you'd like to work with Xapian, but nothing below really appeals and you don't have an idea of your own, feel free to talk to us, and we'll see if we can come up with something suitable.
Click on the idea title in the list below to see more details. Each idea should have an explanation of what it's about, some references for further reading, a list of useful skills to already have, an estimated difficulty, and a list of people who have so far indicated they might be willing to mentor such projects.
Table of Contents
Project: Improve "Getting Started with Xapian"
The "Getting Started with Xapian" guide is where we recommend people start if they want to learn how to use the Xapian API.
The source text of this guide is written in reStructured Text which is then processed using the Sphinx documentation generation tool. We have some custom Sphinx macros for insertion of sample code and the results of running it which allow us to verify that any sample code in the menu actually works and gives the reported results, and these macros also allow us to inserting examples in different programming languages. Along with some other custom macros for marking up mentions of class names, method names, etc in the text this allows us to generate versions of the guide tailored to users wanting to learn to use Xapian from C++, Python, Perl, PHP, Ruby, etc.
Most of the guide has so far been written collaboratively over a series of documentation sprints by various Xapian contributors. However, this means that the tone and style aren't always very consistent, and the overall structure has evolved rather organically.
The idea here is to take the getting started guide and improve it in various ways - for example:
- Improve the structure
- Write docs for topics that aren't currently covered
- Fill in missing translations of example code to other programming languages
- Make the style and tone more consistent
- Read through and check for inaccuracies or out of date information
The custom macros that allow producing versions for different programming languages are important, so continuing to use Sphinx and reStructured Text is probably a requirement.
Resources:
- Git repo with the manual source
- Built HTML version for the Python programming language (hosted on readthedocs)
- Sphinx Documentation Generator
Skills:
- Existing experience with Sphinx and/or reStructured Text would be useful but not essential
Potential mentors: James Aylett, Olly Betts
Project: Improve Xapian API documentation
Our C++ API headers contain documentation comments formatted such that they can be extracted and collated by a tool called Doxygen which can then generate API documentation in HTML and some other formats.
This API documentation is complementary to our "Getting Started" guide - it's useful for people who are already familiar with the API but who need reminding of the details of calling a particular method, or how to use a particular class.
A useful project would be to work through the generated API documentation and and ensure everything is documented, find stuff that's out of date, fix formatting problems, sort out things that aren't clear to someone new to the API, etc.
Resources:
Skills:
- Basic familiarity with C++ would be useful
Potential mentors: James Aylett, Olly Betts
