Sanic: Publish documentation

[wilcoschoneveld]

e.g. with Sphinx integrated it should be possible to import the repository at https://readthedocs.org/.

@seemethere can you facilitate this?

[wilcoschoneveld]

@kdelwat fyi

[kdelwat]

The problem is that Read the Docs doesn't support Python 3.5 syntax natively yet, as discussed here. There seems to be a workaround using Conda in that thread which would be a good solution.

[zkanda]

If you look on that issue, this seems to be it: http://stackoverflow.com/a/36144269

I can send a PR if using conda is an accepted solution here.

[wilcoschoneveld]

IMO conda is a good solution.

[seemethere]

This could be a possibility in the future but I don't see the added benefit just yet. The on-github docs done by @kdelwat seem to work great and if there's not a reason to add complexity then we shouldn't.

[luizberti]

I would say migrating docs into GitHub's built in Wiki feature and allowing for community edits would be a great way to improve the currently bare-boned docs right now.

Besides it taking away much of the overhead from contributing documentation, not having to fork, clone, edit, push, PR, merge or anything, it's also nice having doc contributions separate from actual code contributions. It declutters the PR interface, and is overall less stuff to micro-manage.

[JordanP]

it's also nice having doc contributions separate from actual code contributions.

Nope. Good practice is too treat doc as code, and have it in the same repo.

fork, clone, edit, push, PR, merge or anything

People are very used to this workflow.

Also being not too tied with Github might be a good idea.

[luizberti]

It would not be tied to GitHub at all, it's still a Git repository that will live under github.com/channelcat/sanic.wiki.git, except it will appear integrated into this repo under the _Wiki_ tab instead of as a new repo under channelcat's user.

You can still clone it and move it wherever you want, it's just a git versioned folder of Markdown files (much like what docs currently is) except it has navigation controls and a nice Web editing interface that lets you contribute docs without forking the whole thing and dealing with the bureaucracy of PRs which might be routine stuff for many, but I still believe it's burdensome to most.

It would be a relatively painless thing to implement and try out, and it might lead to more contributions given that it lowers the barrier of effort needed to submit improvements. Might be worth testing out, all it takes is mirroring the Markdown documents from the docs folder into the Wiki and seeing how it goes...

[zkanda]

I think this can be closed: https://sanic.readthedocs.io/en/latest/

@luizberti maybe open a different issue for that?

[seemethere]

I'd agree. I like the wiki style for some things but I think the docs should stay checked in with the code.

Maybe we can agree for some of the docs to go to the wiki (like extensions).

But @zkanda is right I'll close this issue.

@luizberti feel free to open a different issue regarding moving the docs to a github wiki.