Hi all!

I am revising some of my books for online and ebook editions, and using Sublime as my main editor (and loving it!). Found a note that Sublime’s unofficial documentation is written for Sphinx (see bottom of docs.sublimetext.info/en/latest/intro.html). So, I wonder, are there any Sphinx-related tools, highlighters, and especially table generators available for Sublime? Or, are there alternatives to Sphinx (using Sublime as the ed of course) that I might want to consider?

Thanks for any advice.

Tom Swan
www.tomswan.com

I’m sure there are many tools that assist with table generation for Sublime Text, not necessarily tied to be used with Sphinx. Since I work on the unofficial docs (and am doing it in ST), I can tell you that I don’t use any table-assisting package (as I don’t really mess with the tables there) and have restructuredText Improved installed, which imo needs an update. I would rather update the default restructuredText syntax definition however.

packagecontrol.io/search/table
packagecontrol.io/search/restructured%20text

Thanks. My question is not only about tables, although that’s one feature I’m exploring. I’m really wondering about markup documentation systems in general such as AsciiDoc, Sphinx, MarkDown, DocBook, et. al. For doing online documentation that is easily converted to html, pdf, epub, etc formats, what are the current top of the line tools being used? On the page I mentioned before, a note states that ST docs are being written using Sphinx. Is that so and do you and others think that would be a good choice for me to use, for converting existing text (big books, up to 1200 pgs) to online and epub format? (Using ST as my main editor of course images/icons/smile/mrgreen.gif.)

First of all, I grew up reading Mastering Turbo Pascal. You’re that Tom? In that case, big kudos Easily the best TP book ever written.

Everyone seems to use AsciiDoc these days, which is supported by the big guys, like gitbook.com/

I really enjoy using AsciiDoc, because the text version of the document is readable and it’s easy to understand how it maps to the rendered result. Not the mention all the tools and companies supporting this format.

In Shinx the documentation is written in ReStructuredText (.rst) a format supported by Sublime.
I added a build system to my Sphinx project, to build the documentation from Sublime.
The code is below. If you’re on linux or Mac the “make.bat” should be just “make”.
If Sphinx-build isn’t in your path like me, you should try the two commented lines to set the path correctly and run directly the sphinx-build. (command found inside the “make” created by Sphinx).
I was personally interested in html output (for a documentation) but sphinx can also output epub or pdf.

[code]“build_systems”:

    {
        "name": "Sphinx make html",
        "selector": "text.restructuredtext",
        "working_dir": "$project_path/doc",
        "cmd": "make.bat", "html"],
        //"cmd": "%SPHINXBUILD%", "-b", "html", "-d", "_build/doctrees", ".", "_build/html"],
        "shell": true,
        "env": {
            // "SPHINXBUILD": "\"C:\\Program Files (x86)\\Anaconda\\Scripts\\sphinx-build.exe\"",
        },
        "file_regex": "^(.*):([0-9]+): ",
    },
],[/code]

You can check out our sublime-project file here: github.com/guillermooo/sublime- … me-project
So yes, we do indeed use Sphinx, as is also noted in several places (such as on the RTD page, the contributing page and the repository’s readme).

I have to admit that our primary focus currently is also HTML output and not epub or pdf, at the moment at least. You can check out the pdf or epub builds of the undocs in the the popup that opens when you click the small banner on the bottom left. They are not optimized (many empty pages) because we never look at them, but they are still surprisingly okay.

Yeah, that’s me. Thanks for remembering! That was a while ago Please feel free to visit tomswan.com and keep in touch.

I’m just getting into AsciiDoc, but I’ve used it personally for various things. Now I’m interested in using it and related tools for bigger online projects and I’m fishing for whatever I can learn.

[quote]First of all, I grew up reading Mastering Turbo Pascal. You’re that Tom? In that case, big kudos Easily the best TP book ever written.

Everyone seems to use AsciiDoc these days, which is supported by the big guys, like gitbook.com/

I really enjoy using AsciiDoc, because the text version of the document is readable and it’s easy to understand how it maps to the rendered result. Not the mention all the tools and companies supporting this format.
[/quote]

[quote=“gwenzek”]

In Shinx the documentation is written in ReStructuredText (.rst) a format supported by Sublime.
I added a build system to my Sphinx project, to build the documentation from Sublime.
The code is below. If you’re on linux or Mac the “make.bat” should be just “make”.
If Sphinx-build isn’t in your path like me, you should try the two commented lines to set the path correctly and run directly the sphinx-build. (command found inside the “make” created by Sphinx).
I was personally interested in html output (for a documentation) but sphinx can also output epub or pdf.

[code]“build_systems”:

    {
        "name": "Sphinx make html",
        "selector": "text.restructuredtext",
        "working_dir": "$project_path/doc",
        "cmd": "make.bat", "html"],
        //"cmd": "%SPHINXBUILD%", "-b", "html", "-d", "_build/doctrees", ".", "_build/html"],
        "shell": true,
        "env": {
            // "SPHINXBUILD": "\"C:\\Program Files (x86)\\Anaconda\\Scripts\\sphinx-build.exe\"",
        },
        "file_regex": "^(.*):([0-9]+): ",
    },
],[/code][/quote]

Thanks that’s helpful. I am thinking more along the lines of a way to enter tables in Sublime using = and - and + characters to “draw” boxes, columns, rows. Is there an add-on that can do that?

[quote=“FichteFoll”]You can check out our sublime-project file here: github.com/guillermooo/sublime- … me-project
So yes, we do indeed use Sphinx, as is also noted in several places (such as on the RTD page, the contributing page and the repository’s readme).

I have to admit that our primary focus currently is also HTML output and not epub or pdf, at the moment at least. You can check out the pdf or epub builds of the undocs in the the popup that opens when you click the small banner on the bottom left. They are not optimized (many empty pages) because we never look at them, but they are still surprisingly okay.[/quote]

I’m not yet convinced that Sphinx is the right choice for me, but for what you guys are doing, I can understand its value. I like some of the organizing features, but then asciiDoc is also appealing. Just trying to collect as much info as I can before I get into my developing project(s) and then discover I made a wrong choice. I will check out the files you suggest. Thanks for the links.

If you followed my link earlier, you should have found packagecontrol.io/packages/Table%20Editor, which I’m pretty sure of doing what you need. I don’t actually use it myself though.

[quote=“FichteFoll”]

If you followed my link earlier, you should have found packagecontrol.io/packages/Table%20Editor, which I’m pretty sure of doing what you need. I don’t actually use it myself though.[/quote]

Thanks. That is pretty much what I was looking for.

[quote=“TomSwan”]

If you followed my link earlier, you should have found packagecontrol.io/packages/Table%20Editor, which I’m pretty sure of doing what you need. I don’t actually use it myself though.

Thanks. That is pretty much what I was looking for.[/quote]

@tom
Be aware that it’s an unsupported package now (the guy moved on), and is likely to break in future ST versions, so not sure I would start depending on it.