Documentation and Frontend Rejig

Moving forward
#1

This thread of dedicated to the discussion of how to go ahead with revamping effort towards the following items.

  1. Documentation (Tutorial/Wiki/Encyclopedia-like)
  2. Sanic Website Frontend

Starting a new thread to continue the discussions from here

Another New Guy
Frontpage and Documentation overhaul
#2

@harshanarayana Thanks for starting this.

As you mentioned:

I agree with this, and like the UI a lot. I have never used it to create docs, so I am not sure what our choices are for writing on Gitbook (RST, markdown, asciidoc, etc). Right now our docs are a mess of both RST and markdown. Less than ideal.

To rephrase your list, I feel like there are three potentially distinct needs:

  1. Documentation (how to work with Sanic, changelog, etc)
  2. Tutorials, examples, how-to’s (what can be done with Sanic)
  3. Front page (The “face” of Sanic, announcements, quick overview)

The first of this list is what we have on RTD now. The second I suppose is somewhat started on the wiki page. And the third is rather hastily thrown up using GitHub pages and pelican.

Clearly this needs work.

Ideally we are able to combine these into a more seamless and consistent experience.

So, I suppose the first question worth getting input from everyone is what methods do you all recommend (keeping in mind we have limited resources for hosting costs).

Welcome to the Community
#3

I suggest going with Markdown for Tutorial documentation on Gitbook. It’s much cleaner and easy to manager.

It even has support to publish to github and update document on Gitbook based on github commits as well. It has a pretty good section of templates available to enable our use case too.

image
image1226×731 43.2 KB

We have to make a few enhancements to the contribution section to see if we can suggest some commit message standards that can help us in generating a more cleaner and fancier changelog automatically. (eg: Semantic commit messages)

#4

I believe @sjsadowski was looking into that at some point. Not 100% sure.

#5

Oh okay. As an FYI, @ work, I am trying to enforce the use of pre-commit hooks to enforce some standards under linting and commit messages.

#6

Yeah. I want automated changelogs in 2019. :sweat_smile:

1 Like
#7

@harshanarayana , I think I disagree, but I am afraid I am too busy at the moment to give a detailed response. I agree that the first edition is easier to do in markdown, but it will become difficult to maintain later and quite hard to keep external references up to date.

#8

I look forward to the “more detailed response”

#9

Ok, you have been so generous with your experience that I just *have to take a brief break from my insane deadline to touch on the doc subject.

Docs are easy(ish) to write, but hard to maintain

The situation gets even worse where there are “too many cooks in the kitchen”. In long-lived projects (many years, many versions) where there are lots of contributors, keeping docs current is a nightmare. As trust in the docs fails, so does confidence in the project ( cough >jenkins< cough ).

How do the big kids do it?

By way of example, allow me to present a few project we’re all familiar with, because they are similar to Sanic and because we don’t hear people complaining about the docs:

What makes these docs so special?

  • These docs need to be version specific because the code details may change from one release to the next.
  • They also need to be elastic enough that you avoid repeating material that has not changed.
  • There are many cross references because the same info can be relevant to different contexts (eg. Tutorial, Reference, Release Note)
  • If you look at the source you’ll notice the use of symbols like :doc: (which resolves to a URL at compile time) and :term: (which resolves to a glossary entry ).
  • They keep the content and presentation separate, because sometimes the HTML needs to look like a web page and the PDF needs to look like a book… or ePub, man page, or even a fancy presentation

By popular demand, here are a few of my favorites:

I’m excited to try this new Swagger/OpenAPI extension ( example )

3 Likes
Thoughts on consolidating docs to either MD or RST
#10

EXTREMELY useful. I have this one bookmarked so I know to come back and respond better.

#11

@blaisep

Those are some really cool examples of documentation. I didn’t even know about Mermaid.js before you mentioned it here. #bookmarked

#12

Wow, thanks a lot for the effort on taking to us all these notes!

The situation gets even worse where there are “too many cooks in the kitchen” . In long-lived projects (many years, many versions) where there are lots of contributors, keeping docs current is a nightmare. As trust in the docs fails, so does confidence in the project ( cough >jenkins< cough ).

I couldn’t agree more. How many times I got myself lost in old documentation pages simply left in the main branch for reasons I can’t even imagine. Docs that doesn’t reflect the reality of the project.

Well, when it comes to documentation I always brings up SQLALchemy. I know it have it’s own plugins for sphinx and a whole lot of stuff that’s not common for a regular rtd page, but it simply makes everything outstanding - not only integrating real code with docs, but docs from real code …

As from your favorites, I would say that there are a lot of sphinx addons / extensions that are way too handy to be true. versionadded, deprecated and so on … not to mention doctest - there are some classes and functions that can be tested using it in Sanic; but not everything, IMHO. We should try to use doctest whenever possible.

I think we should take some time and see what these projects do with sphinx that makes them so special and start to map them for usage as well.

#13

To be honest, I’m grateful and honored to be able to contribute to such a great group of people. I have spent most of my career helping people adopt software, so I’m happy to share some tricks of the trade.
Python’s motto “Code is read more often than it is written” shows up in the docutils module (a stroke of genius IMHO) and that is what makes things like Sphinx and readthedocs.io possible.

Another stroke of genius is templating and cookiecutter. I think @harshanarayana made a huge contribution with his cookiecutter-sanic project. If I was better at writing tests, I would include some doctest examples. Maybe add a little ansible and a sprinkle of molecule.

#14

I couldn’t agree more. There was a time that I had to read Twisted Matrix’ source code to understand things a little bit better, because there wasn’t enough documentation on how to do certain “lower level” things, so to speak. Not to mention these guy’s been around with their async stuff even before PEP8 was born, so I respect a lot their work. I just migrated to Python 3 and away from Twisted after asyncio was born …

I couldn’t agree more! :beers:

So, I think we can start with some ideas to tweak the documentation. Thoughts on where? Or the weak spots right now?

#15

I really should amend this post to include my candidate for kickass devops style guide:

https://developer.skatelescope.org/en/latest/development_practices/ska_testing_policy_and_strategy.html

#16

Awesome. Will take a look. @steering-council is talking a few things over this week, this is on my list to bring up and push forward.