Roadmap to stable release

[pradyunsg]

This issue is meant to be a planning/dumping ground for tasks that have to be done prior to the first stable release of furo.

• Write the documentation for this theme
  • Finalize skeleton structure.
  • Write the content!
• Deploy the documentation w/ GitHub Pages
• Stylize API documentation
• Stylize captions
• Stylize field lists (low priority)
• Stylize the remaining permalinks
• Switch to em for typography, instead of using rem everywhere
• Tweak spacing for headings & paragraphs -- they might have a little too much margin?
• Fix page's height on mobile, where 100%-100vh is not 0. -.-
• Fix z-index levels for overlay (the toctree overlay needs to be above the sidebar and vice-versa).
• Skeleton + styling for index pages (Generated index pages don't render #50)
• Add JS-based buttons to copy code blocks
• Create a good looking landing page for the documentation

[pradyunsg]

https://github.com/tholman/github-corners is amazing and we should have that at least on the landing page for this theme's documentation (if not available on all pages).

[goodmami]

• Add JS-based buttons to copy code blocks

I suspect you're already aware, but if not, there's https://github.com/executablebooks/sphinx-copybutton/. It also has some support for filtering out prompts (e.g., >>>) when copying.

Btw thanks for this theme!

[pradyunsg]

I suspect you're already aware, but if not,

Even though I'm a collaborator on executablebooks, I didn't know about this. Thanks for the link! I might end up using that! ^>^

[pradyunsg]

Actually, that doesn't need to be done here, or be critical path for the release. :)

[goodmami]

No, but it doesn’t work now because for some reason the `DOCUMENTATION_OPTIONS` object is not being set. I’m not at my computer now but I think it seemed like `base.html` was not being used? Although the “basic” theme also sets it so I’m not sure why it didn’t work. I can take a closer look tomorrow.

…

On Sep 14, 2020, 7:23 PM +0800, Pradyun Gedam ***@***.***>, wrote: Actually, that doesn't need to be done here, or be critical path for the release. :) — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or unsubscribe.

[pradyunsg]

@goodmami Yea, I was trying to reduce the number of assets that are loaded on each page. Turns out, a lot of stuff out there assumes that's not how Sphinx works, and it's likely easier to just mimic it rather than trying to optimize things -- this was fixed in bea26d9.

[goodmami]

Oops, my fault. I was using the version from PyPI which doesn't have that commit. I withdraw my statements above about it not working.
I appreciate your goal to cut out the extra stuff. I hope the situation with Sphinx improves such that it can be realized.

[pradyunsg]

Okay, so there's lots of documentation to write now!

[pradyunsg]

Just #50 is left. And, with that, I think I can move out of betas! :)

[pradyunsg]

I'll mark the releases I make starting next month as stable. :)

[jtpavlock]

Any chance of supporting Sphinx v4 with the next release?

[pradyunsg]

Yup, that's the rough plan. I just need to test it out, since I know that there have been some changes around the HTML output that themes have to work with.

#148 (comment)

[jtpavlock]

Yup, that's the rough plan. I just need to test it out, since I know that there have been some changes around the HTML output that themes have to work with.

#148 (comment)

Missed that discussion, thanks!

[pradyunsg]

Okay, with Sphinx 4 settled down, we're basically there.

I have known for a while that I should write down a "policy document", describing the promises that this theme makes to the users; clarifying the versioning policy, change management policy and support policy. I've been procrastinating on that, but that should probably stay a blocker for "going stable".

[pradyunsg]

Annd... done!

https://pradyunsg.me/furo/stability/
https://pradyunsg.me/furo/changelog/#aspiring-avocado

:)