Sublime Forum

Documentation!

#3

Yeah, great idea.

In terms of format, I’m a big fan of the single-page documentation. Makes doing a find very easy. Something like Backbone’s documentation is a good example of this.

0 Likes

#4

Great ideas - some stuff i’d like to see:

  • How to create a window with specific dimensions and locations to use as console and stdout data
  • Async processes (like running python, nodejs, ruby) that don’t hold up main thread - interactive for running scripts
  • Language defs with tmBundles

I want to re-write my nodejs plugin to be more useful for debugging and would love to implement these features, but not sure how.

0 Likes

#5

If everybody thinks open sourcing the docs is the best thing to do, I’m fine with donating what I’ve done up to now. I’m doing a poor job of updating sublimetext.info these days anyway. However, scattering the docs even more won’t help anybody. I was thinking I could put everything up on GitHub and people would send pull requests, but if we go for a GitHub-only solution, that’s fine too, but I think GitHub might be too intimidating for non-technical users. The really important thing IMO is that everything is in one single place.

There’s also readthedocs.org if we’re sticking with Sphinx (that’s what I’m using now).

As far as organizing the docs, I think there should be a series of main topics and then a sort of a knowledge base where self-contained tutorials, troubleshooting etc. would go.

0 Likes

#6

Well, what’s nice about github is they allow everything to stay together. We could host a basic site through them (see twitter.github.com for an example) and the only time someone would need to interact with git and github would be if they wanted to contribute with a pull request. If anyone has a better wiki based solution, I’d be interested. Github was just the first thing I thought of because many Sublime developers (aka people able and willing to contribute to the ST knowledge base) already use github.

Github makes it pretty simple to set of a site too: sublimetext.github.com/ (setup instructions are on the page)

I completely agree. It’s hard enough that there is Sublime Text 1 and 2 docs hosted here and then more information available through sublimetext.info

0 Likes

#7

I agree that a github based solution is probably better than the previous wiki idea. I was hesitant to set up a wiki straight away since no one voiced much support, and it would only serve to fragment the documentation community.

Happy to offer any assistance putting together docs.

0 Likes

#8

Ok, so what’s the next step? I don’t know anything about setting up a static site on GH, so someone else has to step in.

Open questions:

  • are we sticking to Sphinx?

Sphinx gets my vote. Sometimes it feels too heavy-weight, but it keeps links working and gives you a decent interface and search almost for free. I don’t see any major shortcomings to keep using Sphinx, but others might disagree. We should reach an agreement asap on this; the goal’s to write stuff! :wink: I think nothing stops us from sticking with Sphinx now and gradually migrate the content to a better system if one emerges. And maybe GH imposes some specific format, which actually would makes things easier in a way.

  • license?

All this time I’ve been thinking about eventually releasing the docs source (not that it would be hard to get it now anyway), and for some reason I thought a Creative Commons license would work well. In reality, I couldn’t care less about licenses, but if anybody has strong arguments in favor of one of them, I’m all ears.

  • my next steps

I’ll try and commit the drafts I have lying around so that work, however rough, doesn’t get lost.

0 Likes

#9

There is now a blank github page for sublimetext.github.com
The code (if there was any) can be found here: github.com/SublimeText/sublimetext.github.com

@guillermooo
I’m not familiar with Sphinx so it would probably make sense for you to set up the basic project/structure so that I don’t butcher the entire thing. But I’ll do some more reading about Sphinx so I can help as soon as something’s up.

As for licensing, It really makes no difference to me. I’ll just let someone else deal with that :smile:

0 Likes

#10

Licensing issues may arise from shared code snippets or even full packages. While the site itself can be safely licensed under Creative Commons, individual package documentation would remain under the author’s own licensing terms according to their license file/file header etc. For general site content and contributed code snippets, I lean toward the Attribution-ShareAlike license as it allows commercial use but requires attribution to the original site/author as well as licensing any derivatives under the same terms. I’m fairly open in this regard in that I feel only a derivative code block should be ShareAlike CC-licensed instead of the whole work (unless the whole package is based on a shared code snippet, that is!).

To publish a GH hosted site, we only need to commit an index.html file (+CSS/JS/IMG if not using a CDN) to a repo named sublimetext.github.com. I can see one has already been made so that’s not a problem. What I suggest for package documentation is to have a basic predefined template in a “gh-pages” branch. An author wishing to contribute their own documentation may be added to the SublimeText organisation so they can create their own “gh-pages” branch, or they can fork the template and submit a pull request. The 2nd option is my recommendation for quality control and security.

I prefer Markdown for documentation as it’s well supported by github and a little easier (semantically) than Sphinx. I also quite like the online tool to convert to HTML, making it less complicated to build.

0 Likes

#11

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.

0 Likes

#12

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.

0 Likes

#13

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

documentup.com/tanepiper/sublime-todomanager/

Could maybe be used to our advantage in some way?

0 Likes

#14

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…

0 Likes

#15

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.

0 Likes

#16

I’ll set everything up when I have some time.

0 Likes

#17

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: 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.

0 Likes

#18

Ok, docs pushed:

github.com/SublimeText/UnofficialDocs

Readable site is here:

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.

0 Likes

#19

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 :frowning:
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.

0 Likes

#20

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.

0 Likes

#21

I’ve pushed up a change request to include the keyboard shortcuts page - I’ve split it down into Win/Linux and OSX due to the size - and I’ve kept the tables the same, even though some Mac keys are missing (I have never used bookmarks so I don’t have any default key bindings I know for it).

I’d like to try keep a 1:1 mapping, even if a default key is not set for a OS because RestructuredText tables are a pig and it took me a couple of goes to get right (Key col is up to col 19, the end of the table col 79) and control characters throw off alignment because of their pixel widths.

If anyone feels anything important is missing, just let me know

0 Likes

#22

@tanepiper I merged your changes and added the missing keybindings for OSX. Also, I changed the format for ‘sequences’ from something like command+kb to command+k,command+b because I think it’s easier to understand.

I’ll get around to making my own additions soon.

0 Likes