Sublime Forum

[Undocs]: I'm lost

#1

Hi there!

I love Sublime Text and although it’s documentation is amazingly tiny, the community has been able to create it the unofficial docs.

So, I want to get a bit more involve, and so, I made the first step: I cloned the repo :laughing:

After this, I’m lost. I’ve never used sphinx before (I learned quickly), but I have a serious problem with internal links. I’ve seen that there is no hard written link to other pages of the docs, and sometimes, there’s a :something: the text <different type of thing here>

Sometimes, it’s a path to the .rst file, like this

:doc:`Customization - Settings </customization/settings>`

Sometimes, it’s a name (that, I guess, has been assigned to a link)

:ref:`symbol navigation <fm-goto-symbol>`

So, after messing around, I finaly decided to create this topic, because, I feel like I’m wasting too much time to just add few commands to the reference (I learned a few things about ST, so it’s that much a waste of time, but still)

So, if someone could explain me real quick how that works, I’d really appreciate it!

Matt

0 Likes

#2

Nobody? :frowning:

0 Likes

#3

Hello? @facelessuser @FichteFoll?

0 Likes

#4

@math2001. It’s reStructuredText format. I don’t really use it, and when I have to (and it is only when I have to), I have to look it up to refresh myself. All my docs I generate with MkDocs which is Markdown and Python. Easy peasy.

I don’t bother to learn rst unless I have to ;).

3 Likes

#5

@math2001, Check this out. This will probably help. Just search for :ref: etc. http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html.

3 Likes

#6

Didn’t notice this thread during my small “hiatus”.

Targets for :doc: are filepaths to documents (relative to the current file or project root if starting with /, file extensions are omitted).
Targets for :ref: roles need to be defined manually within the source. You usually need this to refer to sections inside a document.

Sphinx’s documentation is (ironically) pretty hard to navigate, but you can find information on these roles (also called “inline markup”, I suppose) here: http://www.sphinx-doc.org/en/1.4.8/markup/inline.html

3 Likes

#7

Yeah, sphinx is more feature rich, but a for system to make writing documents easier, it is tough to figure out. I assume once your over the learning curve, it gets much easier.

0 Likes

#8

Why use it then? Is there no alternative? (MkDocs as said @facelessuser?)

Does it points to a ref link, or to some content?

So, anyway, thanks!

0 Likes

#9

I think it’s like I said earlier: sphinx is more feature rich.

Some people know it very well and that is what they prefer. I know a guy who loves writing docs in LaTeX…I do not. MkDocs is limited to Markdown (there are a number of extensions that can be used, but it is still more limited).

I think it comes down to whether you want an easy to pick up and use doc system, or a more difficult but more feature rich setup. As awesome as the features are in Sphinx, I don’t have time to learn all that. It just doesn’t feel intuitive to me.

At this point the doc site is already picked, I doubt people are moving the Unofficial docs any time soon.

4 Likes