Add complete TOC and stubs

[ddeboer]

• Improve the TOC and make sure it is complete
• Create stubs for all components

[ddeboer]

Hm, why is the diff broken? Contacted GH support about this.

[sagikazarmark]

LOL. Good question.

[ddeboer]

Okay, have a look at http://php-http.readthedocs.org/en/doc-stubs/ to see the built version.

Is that TOC too long? It may be somewhat intimidating.

[sagikazarmark]

Yes, that was my concern exactly: when we start document every detail, documentation will get too long.

That's why I suggested some kind of separation of the docs, but @dbu is right that it would not make things better: crosslinking, many places for docs.

What I am thinking about now is adding some kind of javascript to make the long blocks (Plugins, Clients, etc) collapsible.

[ddeboer]

Decided to just move the components into a components group.

[sagikazarmark]

Some HTTPlug docs could also be merged ito one page, like virtual package. It is actually documented in the index page as well.

[ddeboer]

Right, but this PR should only be about the general structure. I’ll re-organize the HTTPlug docs in a separate PR.

[sagikazarmark]

Maybe utils could go into clients and adapters section. It has been renamed to client-common anyway.

[ddeboer]

Ah, moving it down one level in the hierarchy doesn’t help. The only solution is to use JS or to stuff all items (clients, plugins) together in one file.

[sagikazarmark]

Yes 😢

[sagikazarmark]

Actually I think the HTTPlug documentation could be in one file.

Where did the development section go?

[ddeboer]

Oops, re-added that.

[dbu]

seems like sphinx/rst can do collapsible menus. see http://foshttpcache.readthedocs.org/

i noticed that the 4th level only opens when clicking on the parent (which is named Home instead of being on the parent) http://php-http.readthedocs.org/en/doc-stubs/plugins/ - but that 4th level is only jump points within the page. can we name those "Introduction" rather than "Home" btw? actually, all of those "Home" would better be on the title of the section than as a first sub-section. is this another limitation of mkdocs?

why is "Message" under "Other Components"? i think that should be on the same level as Plugins and Clients. and have the sub pages for the points listed in the intro: Authentication, Stream encoding, Message decorators, Message factory, Cookie

[sagikazarmark]

seems like sphinx/rst can do collapsible menus

Those are actually one pages, not collapsible menus. We have a problem here when we reach level three, while FOS HTTP cache has only two levels.

Home is the automatic name of index.md. Menu title names are generated based on file name, not on the main title. So we can either workaround this issue by renaming the file to introduction.md or configuring it in the mkdocs config.

When a home section is at the 3rd sublevel, it is because it is included in the folder. If we move it up one level, it will show up there.

[ddeboer]

Yeah, Sphinx works better on RTD.

all of those "Home" would better be on the title of the section than as a first sub-section. is this another limitation of mkdocs?

Yes.

why is "Message" under "Other Components"?

Moved it up one level.

[dbu]

do we need the components main heading? right now, level 1 is

• HTTPlug
• Components
• Development

what if it was

• HTTPlug
• Clients & Adapters
• Plugins
• Message (and move Message Factory in there)
• Promise
• Discovery
• Development

that would kill one level of navigation and provide a more direct approach. i feel that the grouping of "Components" does not tell much.

for the other problems, i guess we either move all plugin docs and all client & adapter docs into one huge .md file or we switch to rst because its better supported. or do we have other viable alternatives?

[sagikazarmark]

If rst solves our level problem, I am not against it. But again: in FOS HTTP Cache, each heading is one file as I can see, so I don't know whether multi level is supported there.

[ddeboer]

i feel that the grouping of "Components" does not tell much.

Yeah, let’s ditch it.

i guess we either move all plugin docs and all client & adapter docs into one huge .md

I’m in favour of this option. Let’s remember that while we (the maintainers) may not like working on long files, the docs are for our users, so how the docs are rendered is more important.

[sagikazarmark]

To tell the truth, sphinx syntaxt highlighting is much better IMO (http://foshttpcache.readthedocs.org/en/stable/proxy-clients.html#varnish-client)

[ddeboer]

Other advantage of Sphinx: spell checker (we use that on FOSHttpCache, too).

@sagikazarmark In FOSHttpCache, we have separated the docs into files, with foldout nav still working: https://github.com/FriendsOfSymfony/FOSHttpCache/tree/master/doc, for instance this one.

The syntax highlighting colours come from a custom CSS. You may be able to do that with MKDocs, too.

[sagikazarmark]

I wonder why mkdocs cannot support it. Well, I think the navigation is a key part of the documentation, so if it works better in sphinx (and it seems generally everything does) then my vote goes to migrating docs to rst. But it's entirely in your hands, I haven't used rst yo far. 😉

[dbu]

i am up to help converting the stuff. most of it looks just the same anyways, it will just be some dig through everything and change some syntax things job. i think we should merge this first and in general be sure there are no open merge requests and wait for github to have fixed the diff view. then we jump into it and push the change through. pretty much every PR done in parallel will be a conflict...

if we are ready, i can have a go at that on monday.

[sagikazarmark]

👍

[dbu]

i think we should still merge this PR, or i can PR against this branch, as the reorganizations started here are valuable.

[sagikazarmark]

Let's merge it when @ddeboer thinks it's ready.