Home Download Buy Blog Forum Support

Documentation!

Re: Documentation!

Postby guillermooo on Mon Feb 20, 2012 1:14 pm

So how does this work? the github.com/SublimeText/sublimetext.github.com hosts the built html files, but if we're using a lightweight markup language to do the writing, where do the .rst/.md files go?

Since I'm pretty sure I won't be converting my .rst to .md myself, I suggest the following:

* we use .rst + Sphinx for the current content and main guide
* we use .md for the knowledgebase
* we create a front page like sublimetext.info that forwards to each of the subsections, and other interesting locations

I like this idea because:

It's fair to assume that people willing to put in the time to write core documentation will take the time to look at other existing topics and get up to speed with Sphinx quickly enough.

I picture the knowledgebase as a collection of disparate tips, tutorials and troubleshooting topics with little or no interlinking: one file, one topic, and that's it. Sphinx doesn't seem to be useful there, except for the full-text index in JS.

It would allow me to push the existing content as soon as I learn where to. Later on, we might think about going Sphinxless, but right now I honestly don't se the urge to.

BTW, I'm also in favor of having two or three gatekeepers for the docs repo and let contributors edit content via pull requests.
guillermooo
 
Posts: 729
Joined: Thu Jul 23, 2009 9:06 am

Re: Documentation!

Postby skaet on Mon Feb 20, 2012 2:54 pm

I'd probably commit the .rst/.md files to the repo along with the built .html files. If we need to make changes then the source is available and version controlled. I understand you not wanting to convert RST to MD but it's better for everyone to settle on a single consistent markup. I prefer Markdown because it's widely used on github meaning no unique documentation between package repo and website repo, but I'm willing to concede in favour of RST simply for the automatic index.

Contributors being responsible for submitting a pull request for a completed page as well as updated home page index is going to go a long way to maintain the overall integrity of the documentation. The gatekeepers being there for quality control and administration obviously.
skaet
 
Posts: 93
Joined: Thu Sep 16, 2010 3:37 pm

Re: Documentation!

Postby tanepiper on Mon Feb 20, 2012 4:59 pm

Just as an FYI there is http://documentup.com that is open source and uses .md to create indexed pages. For example:

http://documentup.com/tanepiper/sublime-todomanager/

Could maybe be used to our advantage in some way?
tanepiper
 
Posts: 68
Joined: Sun Nov 06, 2011 6:40 am

Re: Documentation!

Postby skaet on Tue Feb 21, 2012 12:16 am

I hadn't considered the use of a github service hook. If the repo hits a post-receive URL on readthedocs.org or documentup.com whenever a .rst/.md file is pushed, it can essentially build the html pages and index taking a large logistical load off the authors' and admins' backs...
skaet
 
Posts: 93
Joined: Thu Sep 16, 2010 3:37 pm

Re: Documentation!

Postby C0D312 on Tue Feb 21, 2012 12:38 am

Would someone just make a decision and stick with it?! There are a lot of options, but I don't think we could really go wrong if we just picked something and ran with it. If we find something new down the road, so be it. I don't want to be in the situation of picking what services we use since everyone seems to be familiar with different tools. If someone creates a base for the project, I'm ready to contribute.
C0D312
 
Posts: 1063
Joined: Sun Jul 10, 2011 3:23 am

Re: Documentation!

Postby guillermooo on Tue Feb 21, 2012 11:20 am

I'll set everything up when I have some time.
guillermooo
 
Posts: 729
Joined: Thu Jul 23, 2009 9:06 am

Re: Documentation!

Postby spadgos on Tue Feb 21, 2012 11:42 pm

Don't forget that Github provides a wiki as well as automatic formatted display of markdown... There are entire repos which are just a single README.md file, leveraging GH for the conversion (and for forking/pull requests, etc), see: https://github.com/rwldrn/idiomatic.js/

That said, DocumentUp looks like a perfect tool: markdown (including syntax highlighting), automatic creation of files, single page with sensible navigation. Plus one from me.
spadgos
 
Posts: 121
Joined: Thu Oct 06, 2011 12:49 am

Re: Documentation!

Postby guillermooo on Wed Feb 22, 2012 12:44 am

Ok, docs pushed:

https://github.com/SublimeText/UnofficialDocs

Readable site is here:

http://readthedocs.org/docs/sublime-tex ... index.html

I'll see if I can make sublimetext.info point to RTD.

Everybody can send pull requests to improve the docs now. The RTD site will reflect the latest changes automatically shortly after every commit. Let's see if this setup works fine for us.
guillermooo
 
Posts: 729
Joined: Thu Jul 23, 2009 9:06 am

Re: Documentation!

Postby C0D312 on Wed Feb 22, 2012 12:53 am

Awesome, I just checked it out. Is there anyway to make readthedocs less obnoxious? That footer in particular... Also, apparently the search bar does not search Sublime Docs? I couldn't get it to search for anything other than other doc sites hosted there :(
Not really a big deal, I'm just picky. This will definitely work though. I'll play around with it more and get stuff submitted.
C0D312
 
Posts: 1063
Joined: Sun Jul 10, 2011 3:23 am

Re: Documentation!

Postby guillermooo on Wed Feb 22, 2012 6:54 am

First time I use this service. I played a little bit with other projects' docs before going for it and everything seemed to work just fine. I'll see whether I've botched the config.

Until everything's running fine, sublimetext.info will keep using the old content, though.
guillermooo
 
Posts: 729
Joined: Thu Jul 23, 2009 9:06 am

PreviousNext

Return to Plugin Development

Who is online

Users browsing this forum: Yahoo [Bot] and 6 guests