search

rackspace / rack

A CLI for Rackspace (unmaintained)
Other
81 stars 57 forks source link

Second examples listed in TOC for docs for rack #423

Closed kenperkins closed 8 years ago

kenperkins commented 8 years ago

https://developer.rackspace.com/docs/rack-cli/services/#examples-for-services

In the left rail you can see a second set of examples listed:

image

@ktbartholomew could this be a deconst/template problem?

ktbartholomew commented 8 years ago

It looks like the TOC's are duplicated in the source: https://raw.githubusercontent.com/rackspace/rack/master/docs/services/examples/index.rst

jrperritt commented 8 years ago

@ktbartholomew But it was working up until today I think. I merged some changes but not there. It looks like you added those tocs a while back: https://github.com/rackspace/rack/blame/master/docs/services/examples/index.rst I don't know anything about the formatting/syntax for these, but is the :hidden: not being acknowledged?

ktbartholomew commented 8 years ago

@smashwilson has been most active with the preparers lately, maybe he can weigh in on this.

smashwilson commented 8 years ago

We just turned on the Strider build yesterday, so it wasn't being published automatically until then. Has anyone been manually submitting content in the interim? Otherwise, it's likely that the TOC changes from before have just now been published.

The preparer work I've been doing lately has mostly been in output formatting, writing assets and envelopes to disk instead of over the network. I wouldn't rule out preparer changes as a culprit but nothing jumps out at me right now.

What I'd really like to do is revamp the way we generate TOCs in Sphinx entirely to not require the phony _toc.rst file at all. That's going to be difficult, though.

jrperritt commented 8 years ago

I've been publishing the docs to production, but only for the rack releases.

smashwilson commented 8 years ago

Ah, okay, good.

I'll double-check in the preparer... either way, not respecting :hidden: feels like a preparer bug to me.

jrperritt commented 8 years ago

@smashwilson Were you able to determine if this is a bug in the preparer? If not (or if it isn't), I can look into ways of changing the docs to de-dupe the TOC. I'm not sure whether we need the :hidden: TOC there or not.

smashwilson commented 8 years ago

Well, I'm rewriting the way that TOCs are generated entirely with deconst/preparer-sphinx#64. I haven't worked my way back to this specific case yet :wink:

But, I am guessing that the problem is the two .. toctree directives in docs/services/index.rst. Try nixing the :hidden: one - the document structure will be preserved by the other two toctrees.

jrperritt commented 8 years ago

Try nixing the :hidden: one

Will do. With the ability to preview the docs in staging, I can safely just guess and check until I find something that works.

jrperritt commented 8 years ago

by #437

smashwilson commented 8 years ago

Excellent.

No idea why it was only rendering once before, though.

jrperritt commented 8 years ago

No idea why it was only rendering once before, though.

Yeah, nor I. Oh well. Just another unsolved mystery...