Sphinx Workshop

[Konstantin Molchanov]

Hi!

TL;DR: Let's organize an online workshop for wannabe Sphinx extension developers. See the long version below.

I find Sphinx a very complex piece of software, difficult to hack for a newcomer. Given most techwriters are not professional programmers but rather hobbyists, it's extra hard for them to create new extensions for Sphinx.

To make things worse, there is a clear shortage of tutorials on extension development for Sphinx. There is one official one (http://www.sphinx-doc.org/en/master/extdev/tutorial.html) and one by Eric Holscher (http://ericholscher.com/blog/2016/jul/25/integrating-jinja-rst-sphinx/).

Take me for example. I am a techwriter and a hobbyist Python developer. I desperately want to learn Sphinx's internals and develop extensions on a regular basis. But due to lack of learning materials, I give up time after time. I am sure there are others who suffer like me—wanting to give back to the community, but not able to.

I see it as a major problem with Sphinx. We need more great extensions for more tasks to make Sphinx more universal and widely used.

How about we organize an online workshop about Sphinx extension development? Let the experts teach on real-life examples, with real time feedback. I know I would participate, and I know a couple of people who probably would too.

If you find the idea worth discussing, let's discuss! Feel free to share you pros and cons, suggestions and considerations.

[Matthew Brett]

Hi,

I think that's an excellent idea. I'm sure it would be useful for
development on core Sphinx as well. I've written quite a few sphinx
extensions now, but I still find it hard to work out the sphinx
internals, and I really miss having a definitive set of example
extensions with best practice in them.

Best,

Matthew

[Konstantin Molchanov]

Hi, Matthew!

I agree that a workshop would benefit all: beginners like me, seasoned developers who want to dive deeper like you, and core developers like Komiya Takeshi. For the core developers, this is a great chance to hear the feedback about the product they're working directly from the people using it.

It would be perfect to have a coding session for each interested party:

- Basics. Learn the basics of Sphinx extension development, create a simple extension: custom directive, custom index, etc. A practical example that comes to mind is develop the tags extension that would allow tagging pages and searching by tag.

- Advanced. Learn deeper concepts and real-life problems. Create a more complex extension involving event handling and custom doctree composition. A practical example that comes to mind here is a develop a custom domain or write a converter from Apiblueprint, Swagger, or Apidoc.

- Core. Learn the internals of Sphinx and how to contribute to the core. Since I'm not a seasoned Sphinx developer by a wide margin, I have no idea what the practical example could be :-)

I don't think it's fair to make a single person do all the sessions, so we need at least three volunteers that would take on a session each.

I don't know how long a single session should be, so if you have any experience with similar stuff, please do share your thoughts.

Thanks!