I have spent some time looking into these improvements and put together a proposal for a few changes to https://doc.wikimedia.org/pywikibot/master/:

1. Replace the current theme with Furo (https://pradyunsg.me/furo/) for a more modern look and feel and some additional functionality.
2. Modify content structure to make navigation a bit easier.

As a result, the documentation could look like in the screenshots below:

While change 2 does not explicitly rely on change 1, the separation of local (on the right) and global (on the left) navigation in Furo looks really impactful. We could replicate a part of that functionality (global navigation on the left) in the current theme, but local navigation on the right would take too much work to be achievable with the current theme at the moment.

I will be preparing a pull request with these changes shortly, but wanted to first reach out and gather preliminary feedback. I'm also happy to discuss this on IRC or during a live session with anyone interested. Note that this is a very early draft that I hope we'll be able to improve together.

The complete list of proposed changes:

• Change theme to Furo.
• Add the sphinx-opengraph extension.
• In Furo, customize edit links to allow readers to access source RST files in the repo easily.
• Allow users to navigate between pages using arrow keys (left for previous, right for next).
• Change pygments styles for light and dark modes.
• Add make mini to Makefile as a way to quickly rebuild docs after minor changes.
• Remove redundant content in the navigation structure.
• Introduce documentation sections "User guide", "Bot developer guide", "Pywikibot contributor guide", and "Other" - replacing existing "For bot users", "For bot developers", "For framework developers".
• Introduce new sections on multiple pages to ease on-page navigation using the right-side menu
• Introduce minor style changes.

FYI @Xqt @komla @srishakatux @TBurmeister @apaskulin

I like this new theme. The right side navigation is good for the Sphinx 5.2+ changes which creates toc entries for each function/class/method. It is easier to customize because a lot of changes may be made in conf.py instead of the css file. In addition to your list obove I have some other points:

• colorize with standard colors (dark green,, dark blue, dark red and possibly brightened)
• navigation between pages should be on top of the page instead on bottom if possible
• the navigation bar is missing (hierarchy, prev, next, modules, index)
• the option lists looks good. I think we can give up our customized indentation of help strings.

To summarize I guess it is a good way to go.

Thanks @Xqt, I'll see if I can make the changes you listed, but I'm not sure what you mean by "colorize with standard colors". Are you referring to the CSS customization from pywikibot.css (for links and code blocks), or is it something else?

I'm not sure what you mean by "colorize with standard colors"

I meant the wmf colors #900 (red), #396 (green), #069 (blue). Brightness should be changed via HSB color system. For example links are colored with #7D9FFD (blue) but should become #069 or #006699. The brown color #C44444 should be replaced by #900 i.e. #990000 etc. Indeed I changed some colors for 'natural' theme to 'standard colors'; I needed the css file because 'natural' does not allow customizing much.

OK, I'll try to include this in my pull request early next week. If I miss anything, we can adjust it as part of the review.

Which makes me wonder - do you think it makes sense to set up a test/demo site with these changes somewhere? This would allow us to see the end result and discuss specifics or make immediate adjustments outside the PR in gerrit. This could be on a separate branch, or in a fork. Or do you think building locally and reviewing via gerrit is fine? All of these options work for me.

We already have a tests branch at dwo: https://doc.wikimedia.org/pywikibot/tests/py-modindex.html and I re-created the tests branch for pywikibot-core that all changes and reviews can be done there step by step and merged later to the master branch. To have it at dwo may be an advantage for inventing people to give comments without they have to need installing furo and sphinx locally e.g. for toolforge operators.

Unfortunately running furo on jenkins needs a lot of time (15 minutes or so) and is probably killed due to timeout. 'natural' only needs 2 minutes.

Change 855864 had a related patch set uploaded (by Xqt; author: Xqt):

[pywikibot/core@tests] [doc] Use 'furo' sphinx theme instead of 'natural'

https://gerrit.wikimedia.org/r/855864

Change 855868 had a related patch set uploaded (by Xqt; author: Xqt):

[integration/config@master] [pywikibot/core] Increase tox-doc-docker timeout

https://gerrit.wikimedia.org/r/855868

Change 856167 had a related patch set uploaded (by Xqt; author: Xqt):

[pywikibot/core@master] [doc] Enable sphinx options with make.bat file

https://gerrit.wikimedia.org/r/856167

In T322212#8388772, @Xqt wrote:

Unfortunately running furo on jenkins needs a lot of time (15 minutes or so) and is probably killed due to timeout. 'natural' only needs 2 minutes.

That's a huge difference. I wonder if we can perhaps make it faster by adding `-j auto to Sphinx options (after -a`) to enable multi-threaded processing. Not sure if Jenkins jobs get more than one core to work on but perhaps it's worth a try? I know it cut full rebuild time by 63% on my local machine.

In T322212#8392006, @KBach wrote:

That's a huge difference. I wonder if we can perhaps make it faster by adding `-j auto to Sphinx options (after -a`) to enable multi-threaded processing. Not sure if Jenkins jobs get more than one core to work on but perhaps it's worth a try? I know it cut full rebuild time by 63% on my local machine.

I prepared several changes in T322979. The idea is to run tests with "nature" theme (or "basic" would also work) and publish the documentation with "furo":

• https://gerrit.wikimedia.org/r/c/integration/config/+/855868/ splits "doc" tests into 3 tasks. One for rstcheck, one for sphinx with "nature" theme and one for publishing with "furo"
• https://gerrit.wikimedia.org/r/c/pywikibot/core/+/856176/ implements these checks in tox
• https://gerrit.wikimedia.org/r/c/pywikibot/core/+/855864/ changes the theme to "furo" in a new branch "tests"; "tests" should hold all documentation changes until they are finally merged to master branch.

OK, thanks for looking into this. I'll add my changes on top of these once they are all merged into the tests branch.

The new theme seems much more newcomer friendly! Happy to test more when the changes are live. For the navigation, in addition to allowing switching between pages via arrow keys, I wonder if another alternative could be added, like in the existing theme, we have "prev" and "next" buttons both on the top and bottom. In any case, it might also be helpful to have a "scroll to the top" option on the bottom of every page so one can easily switch back to the content on the top (and access the navigation sidebar on the left too), as some of the pages with code in them are too long.

@KBach I think the colors @Xqt are referring to are coming from the style guide; in case you haven't seen this yet, here it is:
https://design.wikimedia.org/style-guide/visual-style_colors.html

Thanks @srishakatux - these are very good points, and I'm happy to report that the new theme already provides most of these features (highlighted in the screenshot below):

Menu scrolling is independent from page scrolling, so you always have access to both menus, regardless of where you are on a page.

Style-wise, I'll still look into adding the prev and next links to the top of the page somewhere, as well as changing the colors you described.

The new theme looks great! The separation between the local and global navigation makes it easy to navigate the site and understand what content is available. I also love the edit button and the dark mode switch. Since this content is mostly reference material and not strictly sequential, I think it's fine to keep the "prev" and "next" buttons at the bottom of the page. For the navigation headings, I like the clear distinction you've proposed between "User guide", "Bot developer guide", and "Pywikibot contributor guide". Great work!

Change 855864 merged by jenkins-bot:

[pywikibot/core@tests] [doc] Use 'furo' sphinx theme instead of 'natural'

https://gerrit.wikimedia.org/r/855864

I've merged furo theme to tests branch now. The result (and all further changes to this branch) can be viewed here. I'll improve the test task later as soon as https://gerrit.wikimedia.org/r/c/integration/config/+/855868 was merged.

In T322212#8400178, @Xqt wrote:

I've merged furo theme to tests branch now. The result (and all further changes to this branch) can be viewed here. I'll improve the test task later as soon as https://gerrit.wikimedia.org/r/c/integration/config/+/855868 was merged.

It looks great, thank you. I'll submit my changes to the tests branch for review shortly.

I agree with other feedback; this is a great improvement and the navigation is looking wonderful. Like Alex commented, because these are reference docs, they are not likely to be read sequentially, so I don't see any need to keep prev/next buttons at the bottom of each page. One thing that is odd to me, but could just be my lack of familiarity: the "Framework Modules Overview" diagram on the landing page seems overwhelming and out-of-context. As someone who arrives at these docs without an understanding of the topic, I don't know what "framework modules" are, and this diagram doesn't help me understand that. I suggest you move it to a page where that is explained, or add more explanatory text above the diagram to orient readers.

Change 859448 had a related patch set uploaded (by KBach; author: KBach):

[pywikibot/core@tests] [doc] Improve documentation look and feel

https://gerrit.wikimedia.org/r/859448

In T322212#8410192, @TBurmeister wrote:

Like Alex commented, because these are reference docs, they are not likely to be read sequentially, so I don't see any need to keep prev/next buttons at the bottom of each page.

The current sequence can be viewed here.

@KBach: The last change looks like this for highlighted code in dark mode:

Seems the color scheme is taken from light:

 @media screen and (prefers-color-scheme: light)
.viewcode-block:target {
  background-color: #e3e3e3;
  border: 1px solid #a0a0a0;
}

I'm having trouble replicating this locally (or even just making sure I'm testing these snippets correctly in different modes), so I'll remove this change from the current PR. I created a separate sub-task for re-introducing the highlighting: T323800.

Change 859448 merged by jenkins-bot:

[pywikibot/core@tests] [doc] Improve documentation look and feel

https://gerrit.wikimedia.org/r/859448

All improvements we had planned for doc.wikimedia.org/pywikibot/tests have now been merged.

@Xqt please let me know if you feel there's more work to be done here. If not, I think this is ready for release.

In T322212#8453980, @KBach wrote:

All improvements we had planned for doc.wikimedia.org/pywikibot/tests have now been merged.

@Xqt please let me know if you feel there's more work to be done here. If not, I think this is ready for release.

I sent a mail to pywikibot@lists.wikinedia.org for RfC.

Change 871264 had a related patch set uploaded (by Xqt; author: Xqt):

[pywikibot/core@master] Merge branch 'tests' into T322212

https://gerrit.wikimedia.org/r/871264

Change 871264 merged by Xqt:

[pywikibot/core@master] Merge branch 'tests' into T322212

https://gerrit.wikimedia.org/r/871264