New theme for our documentation #159
Conversation
|
One thing that I don't understand is how and why the left bars "Section navigation" is always empty. Maybe some restructuring of chapters/content would be required to make use of that. Everything seems to be on the very right "On this page" navigation. See for comparision in the beets.io docs, "Section Navigation" is populated, I need to investigate why it works there.... https://beets.readthedocs.io/en/stable/reference/config.html |
|
@JOJ0 Looks cool, I'm all for it! |
|
I like it. I looked at the PyData Sphinx page, too, which I liked. It made me think of re-organizing our content a bit if we move to that theme, but one thing at a time. 😀 |
|
Unfortunately there is one thing that is worse with this theme and I don't know how to fix it. Vertical spacing here seems off - it's "way too much" in my opinion: 
With the readthedocs theme it didn't use that much space 
Can we live with that? |
|
One thing I changed "content wise", is restructure the Python docs by inventing another level of index. See 0cd0b2a for details Basically it separates the huge "one page" Python API documentation into single pages and let's us switch with the "Section Navigation". I think this is much more "navigation friendly" now. So now a combination of left and right sidebars can be use to navigate more comfortably even though it's rather a lot of content: 
|
I agree that re-organizing could further improve the "navigateabilty" (that a word? 😆 ). I'm happy to help and review if you want to work on it. One thing I just found out is how to do "subindexes" which helps structuring better. See the changes I did in above mentioned commit. It should get you started for this type of restructuring. |
I can. Not a showstopper for me. You guys? Showstopper for me right now is a lot of new warnings. Will post this weekend hopefully. |
Sorry for the late response - that's not a showstopper for me, either. I'm a bit busy this month, but I should have some time in a couple weeks to work on the docs. |
No worries, sounds perfect, whenever you find the time, or not. Our docs are not bad at all right now! So no stress in there! :-) Thanks for your opinion, on that "too much spacing issue". Yeah let's move on. When there is an actual comment on that specific property, it does look ok by the way: 
Regarding the sh**load of warnings I was getting....I can't reproduce anymore and I'll leave it be for now and merge this :-) Just for reference, and if you come across something like it next time you work on the docs, I got a lot of I'll spare us the whole output, it's repeating that line for all kinds of code parts. Also note: The first 4 lines I just realized are "expected", we have them in a "master" build as well, and live with them since ever ( Just a reminder that you will most probably get them when working on the docs next time :-) Ok, let's merge. |
- This enables "Section Navigation" - Each module has it's own .rst file with a "main section headline", - and is bound together by a "subindex" defined by index_discogs_client.rst
Hi @AnssiAhola and @prcutler,
in the past we put a lot of effort in our documentation. We also have quite a lot of content and I think we deserve a modern looking and feature-rich layout.
What do you think of changing our docs theme to the PyData theme? Since I did this elsewhere I learned some customization possibilities. One default feature of PyData that I think fits our docs, since sometimes we have rather long main chapters, is the "secondary navigation" that helps to easily switch chapters from within one main chapter.
If you don't like this theme at all, I can certainly apply another one and we re-evaluate. I enable this PR branch on readthedocs so we get a live view.
https://python3-discogs-client.readthedocs.io/en/docs_theme/index.html