Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Section names don't get displayed in the readthedocs theme #175

Closed
d0ugal opened this issue Oct 23, 2014 · 16 comments
Closed

Section names don't get displayed in the readthedocs theme #175

d0ugal opened this issue Oct 23, 2014 · 16 comments

Comments

@d0ugal
Copy link
Member

@d0ugal d0ugal commented Oct 23, 2014

Another one to relate to #127.

Currently down the left we just have a list of page names without the sections dividing them up.

@d0ugal d0ugal added the Bug label Oct 23, 2014
@d0ugal d0ugal added this to the 0.10.0 milestone Oct 23, 2014
@d0ugal d0ugal added this to the 0.11.0 milestone Oct 23, 2014
@d0ugal d0ugal removed this from the 0.10.0 milestone Oct 23, 2014
@d0ugal
Copy link
Member Author

@d0ugal d0ugal commented Oct 23, 2014

In the MkDocs "native" themes we support sections. See the top of http://www.mkdocs.org/ where we currently have "User Guide" and "About".

On the ReadTheDocs theme we don't have this. It can be seen on http://mkdocs.readthedocs.org/en/latest/

Loading

@d0ugal
Copy link
Member Author

@d0ugal d0ugal commented Oct 23, 2014

We don't have an obvious "fix" for this as it is a feature that doesn't exist in Sphinx - so we will need to make an addition to the ReadTheDocs theme for it.

Loading

@ericholscher
Copy link
Contributor

@ericholscher ericholscher commented Oct 23, 2014

Paging @snide who might have thoughts on how this might be done well. We
could even add the styling back to the RTD theme, once we finally fix the
toctree generation code to support sections, it would be great to have.

On Thu, Oct 23, 2014 at 1:49 PM, Dougal Matthews notifications@github.com
wrote:

We don't have an obvious "fix" for this as it is a feature that doesn't
exist in Sphinx - so we will need to make an addition to the ReadTheDocs
theme for it.


Reply to this email directly or view it on GitHub
#175 (comment).

Eric Holscher
Maker of the internet residing in Portland, Or
http://ericholscher.com

Loading

@snide
Copy link

@snide snide commented Oct 23, 2014

It would likely look similar to what I did for Webhook's docs, which is just a slant of my RTD theme (with lessons I learned along the way).

http://www.webhook.com/docs/installation/

Whenever RTD adds sections and proper menus just ping me. I don't have much time for the project these days and generally abhor working in Sphinx's nest of jinga code, but can find a day or two to get RTD up to speed with a refresh.

Loading

@d0ugal
Copy link
Member Author

@d0ugal d0ugal commented Oct 23, 2014

Ooh, that looks nice. Is the Webhook theme open source? I can't see it obviously under the github account (but I am on my phone)

Loading

@snide
Copy link

@snide snide commented Oct 23, 2014

Webhook is MIT. The docs themselves are built with Webhook itself, not Sphinx, so I think you'd have a bit of time converting it for your system.

Loading

@ngzhian
Copy link
Contributor

@ngzhian ngzhian commented Oct 31, 2014

Seems like slight modification of the toc.html template in RTD theme folder, with a bit of CSS is sufficient to achieve this:
rtd
this is on branch ngzhian/mkdocs:section-names-in-rtd

Loading

@d0ugal
Copy link
Member Author

@d0ugal d0ugal commented Oct 31, 2014

@ngzhian Neat, that looks good. I'd be happy to merge that in for now. Can you turn that into a PR?

Loading

d0ugal added a commit that referenced this issue Nov 6, 2014
Implement #175: Display section names in RTD
@janmeier
Copy link

@janmeier janmeier commented Nov 6, 2014

@ngzhian's change has been added to master, so it seems this issue can be closed.

Is the code already deployed on readthedocs.org, or do I need to include the latest version of the theme in my repo and use theme_dir in mkdocs.yml?

Loading

@d0ugal
Copy link
Member Author

@d0ugal d0ugal commented Nov 6, 2014

This wont be on RTD yet, they may need a new release, which I can do. Otherwise, maybe if I ping @ericholscher it will magiclaly happen ;)

Loading

@nfarrar
Copy link

@nfarrar nfarrar commented Nov 9, 2014

I'm unsure if this is the same issue as the one described above or not.
The RTD theme is only displaying the section contents on some pages - when a single page is specified in mkdocs.yml (not nested documents):

pages:
- ['index.md', 'Crib']
- ['usage.md', 'Usage']
- ['hacking.md', 'Hacking']
- ['development.md', 'Development']
- ['about.md', 'About', 'About']

You can see here that the sections are displayed appropriately on the about page, but not the others.

Loading

@d0ugal
Copy link
Member Author

@d0ugal d0ugal commented Nov 9, 2014

Ah, interesting. I think this is a slightly different bug. Did you build that with the latest version on PyPI? If you can confirm it is an issue in master too that would be useful.

Loading

@d0ugal
Copy link
Member Author

@d0ugal d0ugal commented Nov 9, 2014

... looking a wee bit more, I'm almost 100% certain this is a different bug. So probably best to move to a new issue.

Loading

@nfarrar
Copy link

@nfarrar nfarrar commented Nov 9, 2014

@d0ugal Yup, installed from pip:

$ pip freeze | grep mkdocs
mkdocs==0.10

Loading

@d0ugal
Copy link
Member Author

@d0ugal d0ugal commented Nov 14, 2014

@nfarrar ok, so this is fixed in master. See the discussion in #218. I'm preparing to do a release shortly.

Loading

@d0ugal d0ugal closed this Nov 14, 2014
@nfarrar
Copy link

@nfarrar nfarrar commented Nov 15, 2014

@d0ugal thanks :)

Loading

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
6 participants