sphinx-themes / sphinx-themes.org Goto Github PK

View Code? Open in Web Editor NEW

227.0 8.0 43.0 593.26 MB

A showcase for Sphinx documentation themes

Home Page: https://sphinx-themes.org

License: BSD 2-Clause "Simplified" License

Python 79.65% HTML 20.35%

showcase sphinx sphinx-theme documentation-themes sphinx-themes pypi

sphinx-themes.org's Introduction

sphinx-themes.org

A Sphinx Themes Gallery, curated by @pradyunsg and @shirou.

This project exists to be a showcase for Sphinx themes and we'd like to include all reusable themes available on PyPI.

Contributing

If you find new theme on PyPI, please file an issue or, even better, a PR for adding it. Our Contributing Guide contains the details for how to add a new theme, how to work on this project and about how this website is generated and hosted.

Acknowledgements

This project is made possible by the work of many contributors.

@shirou: created this website and manages hosting.
@pradyunsg: redesigned the website and site generation pipeline.
All the theme authors: this would not be possible without their work!

sphinx-themes.org's People

Contributors

Stargazers

Watchers

sphinx-themes.org's Issues

lexer "none" does not exist

I checked the pydata-sphinx-theme with doc8 and the block kitchen-sink raised the following error:

docs/examples/kitchen-sink/blocks.rst:244: D000 Cannot analyze code. No Pygments lexer found for "none".

From what I understand the demo is more about the "neutral" lexer more than the exact "none". What about removing it ?

What's the scope of this site?

Moving this out of a merged PR, so that it's more visible and easier to reference in the future.

The first motivation of sphinx-themes.org is to publish as many themes as possible. Otherwise, I wouldn't have had to do such a large amount of work. My idea is that even if the theme is old or not maintained, I want to publish it as it is because someone might be inspired by it. I also want to show that there are so many themes in Sphinx, even if they are mixture of good and bad.

Also, I do not have a solid axis of what is a good theme and what is a bad. That's why I don't want to "curate".

Originally posted by @shirou in #73 (comment)

Add permalinks for each theme, to homepage listing

Doing https://sphinx-themes.org/#{{theme-name}} auto-scrolls to that theme's screenshot on the homepage + make the names of themes into links to those anchors.

I expect this to be a matter of:

adding ids to the theme's overall <div>
making themes names into an anchor tag with a permalink to #{{theme.name}}

Add sphinx-typo3-theme

Please add the new Sphinx Typo3 Theme (successor of t3SphinxThemeRtd).

PyPI: https://pypi.org/project/sphinx-typo3-theme/
Repository: https://github.com/TYPO3-Documentation/sphinx_typo3_theme

the pydata-sphinx-theme is crashing

With sphinx 6 we had lots of issues with the logo management, problems that will be solved in v0.13. pinning @choldgraf to add an example to my point: we should make patch releases instead of release candidates as many are relying on the released version

Get rid of "display" name?

I think for users those two things are important:

the exact theme name as used in html_theme
the exact PyPI package name

Currently, none of them is immediately visible on https://sphinx-themes.org/.

I guess the PyPI name can be inferred from the URL of the examples, but AFAICT the theme name isn't available at all.

I think instead of the "display" name, the html_theme name should be used as the title of the example boxes, but I think adding the PyPI package name to be immediately visible would also be helpful.

What do you think?

Thoughts on a revamp?

Following #3 (comment), I spent a few cycles iterating on this and came up with https://github.com/pradyunsg/sphinx-themes. I added a few themes to demonstrate the approach and a very basic/minimal index page for this, which is online now.

I started from-scratch and came away with quite a different approach for doing things. This resulted in:

Generating demos, and screenshots (w/ selenium) in a GitHub Action job.
Keep all theme-related information in a JSON file.
No requirement on docker -- plain Python scripts w/ nox.
No generated HTML/CSS/images are checked into the master branch.
Preview images contain multiple viewport sizes! 🎉

Notably, the main changes due to all of this are:

Significantly lower barrier for adding new themes! 🎉
Themes have to be installable from PyPI, usable against the current Sphinx version
- This is a reasonable assumption, and helps ensure that people can actually use the themes. :)
No conf.py is included/provided
- The theme should have documentation about this, so the gallery doesn't need to cover this.
- It should be easy-enough to add this if we really want to (I don't)
2 column vs 3 column layout
- I wanted this to include additional viewport sizes, so, yea, I think this design change is worthwhile. :)

This was mostly an over-the-boring-day thing, and there's definitely scope for improvement in the automation (eg: separating render-with-themes vs generate-screenshots). If there's interest in bringing in most (all?) of that codebase into this one, I'd like to hear about it! ^>^

Could not open the "How to create" from sphinx-themes.org

I went to https://sphinx-themes.org/ and from the top left menu, then I chose the "How to create" link. It brought me to https://www.sphinx-doc.org/en/master/theming.html#creating-themes which is 404.

It would be great if the url can be fixed somehow. Thanks.

Provide a link to the Sphinx documentation about using a theme

I suspect that many people landing on this website will be new to the Sphinx ecosystem, and will be trying to find a theme that works with their documentation. For many, it may be unclear how to set a new theme in the Sphinx configuration and this is the first site they land on. It would be helpful if there were a link somewhere on the website that said something like "For information about how to configure Sphinx to use a theme, see the Sphinx theming documentation"

Please add Sizzle theme

Please add this theme:

https://github.com/vsajip/sphinx_sizzle_theme

Available from PyPI:

https://pypi.org/project/sphinx-sizzle-theme/

Please update documentation link for sphinx-sizzle-theme

The documentation for this theme is on the Web at

https://docs.red-dove.com/sphinx_sizzle_theme/index.html

Thanks!

Issue with html_logo configuration

Using the Pylons theme and I am not able to change the favicon nor the logo file using configuration items in conf.py:

html_logo = '_static/bblogo-small.png'
html_favicon = '_static/favicon.ico'

Both of those files are in the _static directory, and I get no errors making the docs. It just seems to ignore them.

$ ./make.bat html
Running Sphinx v1.8.5
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 6 source files that are out of date
updating environment: 6 added, 0 changed, 0 removed
reading sources... [100%] troubleshooting/index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] troubleshooting/index
generating indices... genindex
writing additional pages... search
copying images... [100%] assembly\Bottom.PNG
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.

The HTML pages are in _build\html.

New theme: sphinx-immaterial

sphinx-material theme is not being updated since 2021. It's actually quite old fork of mkdocs-material theme, and the divergence happened a long time ago.

The most recent fork of original theme is now a sphinx-immaterial. It is actively maintained, and has a lot of new features missing in sphinx-material.
https://jbms.github.io/sphinx-immaterial/

Example of a project which uses this theme: galois
https://galois.readthedocs.io/en/latest/

It will be great if this new there will be added to sphinx-themes. And maybe even replace outdated sphinx-material

Permitting multiple themes from a single PyPI package

One Sphinx theme packages can have multiple themes. However, v2 can not handle such a package. A package can have a only one theme.

Example

pylons-sphinx-themes has pylons, pyramid, and pylonsfw themes.

Add tag-based filtering

This would allow users to filter through the long list of themes based on some characteristic of the themes.

Here's my starting list for potential tags we can have.

Layout:

"two-column"
"three-column"
"centered"
"responsive"

Number of knobs:

"can-change-colors"
"can-change-content-width"
"can-change-layout"

[idea] Sub-divide themes

IMO it would be better if the front-page showed less themes.
There is a lot of themes there are just a small variation and/or branding of another theme.

What about front-page show only the main theme and its variations being displayed on another page?
This way it would make it easier to explore available theme families,
and after selecting a base theme a user could see its variations.

ps. You know i am an author of a theme, so I am biased here...

Ensure all builds succeed without any warnings

Currently, builds other than that of Furo fail, due to the documentation set trying to include text from Furo's own sources.

This should be changed to a generic package (likely Sphinx itself).

Theme copyright

Hi,

Does the BSD license apply to every theme in the page? Is there any specific restriction for their use?

Thanks.

pip install PSphinxTheme Error.

I can't install on windows.

pip install PSphinxTheme
Collecting PSphinxTheme
  Using cached https://files.pythonhosted.org/packages/9c/c3/ef591d625532110a7ca544cc24e89422242836247f24da75f94f85d46dd7/PSphinxTheme-2.0.5.tar.bz2
    ERROR: Command errored out with exit status 1:
     command: 'C:\scoop\apps\miniconda3\4.7.12.1\python.exe' -c 'import sys, setuptools, tokenize; sys.argv[0] = '"'"'C:\\Users\\o\\AppData\\Local\\Temp\\pip-install-p5lu_16l\\PSphinxTheme\\setup.py'"'"'; __file__='"'"'C:\\Users\\o\\AppData\\Local\\Temp\\pip-install-p5lu_16l\\PSphinxTheme\\setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(__file__);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' egg_info --egg-base 'C:\Users\o\AppData\Local\Temp\pip-install-p5lu_16l\PSphinxTheme\pip-egg-info'
         cwd: C:\Users\o\AppData\Local\Temp\pip-install-p5lu_16l\PSphinxTheme\
    Complete output (5 lines):
    Traceback (most recent call last):
      File "<string>", line 1, in <module>
      File "C:\Users\o\AppData\Local\Temp\pip-install-p5lu_16l\PSphinxTheme\setup.py", line 62, in <module>
        '''.format(sys_version_info[:2][0], sys_version_info[:2][1], TESTED_HOST_OS))
    IndexError: tuple index out of range
    ----------------------------------------
ERROR: Command errored out with exit status 1: python setup.py egg_info Check the logs for full command output.

Port all themes in current website, to v2 website

This issue contains the list of themes in the current v1 website. As we add themes to v2 (or decide to not add them due to issues), we'll document it here.

Additional:

"Build failed" in pydata demo

https://sphinx-themes.org/sample-sites/pydata-sphinx-theme/ currently displays:

Removed unmaintained themes from "featured" list?

Nothing against those themes, but I think they shouldn't be "featured".

Alabaster
- last release in Oct 2018: https://pypi.org/project/alabaster/#history
- no more activity on Github (even though there are many issues and PRs): https://github.com/bitprophet/alabaster
Redactor
- only one release ever, in July 2017: https://pypi.org/project/sphinx-redactor-theme/#history
- repo doesn't seem to exist anymore: https://github.com/testthedocs/sphinx_redactor_theme

Celery, Insegel and Press don't seem to be very active either, but probably they are just very stable and bug-free?

The situation with Alabster is strange because it's Sphinx's default theme, but that doesn't change that it's not maintained anymore.

Themes are not available

Most of themes are not available and shows build failed. Also, I am trying to install book & furo theme but unable to do so. Ia m gettingpip install sphinx-book-theme DEPRECATION: Python 2.7 reached the end of its life on January 1st, 2020. Please upgrade your Python as Python 2.7 is no longer maintained. pip 21.0 will drop support for Python 2.7 in January 2021. More details about Python 2 support in pip can be found at https://pip.pypa.io/en/latest/development/release-process/#python-2-support pip 21.0 will remove support for this functionality. ERROR: Could not find a version that satisfies the requirement sphinx-book-theme (from versions: none) ERROR: No matching distribution found for sphinx-book-theme

New theme: <no PyPI name, from manticore-projects.com>

Greetings!

I have been searching for a very long time for suitable theme, but did not really find anything pleasant:

most themes do not cater very wide screens well
color and styling is debatable
no landing page support

The nicest theme matching my taste is REVITRON, however it has technical shortcomings.

Long story short, I ended up with developing my own theme, forking from https://github.com/readthedocs/sphinx_rtd_theme

It scales very well on wide screens and mobile phones, it has a landing page, it supports 2 accent colors and it does not need NodeJS or NPM.

You can see it in action here: http://manticore-projects.com

At the moment, the theme is merely a Blob, which one would drop into the ./_themes folder. No PIP/Python involved or need.

Would you be interested in listing it? And what would you need from my end to make that happen please?

Suggestion for a theme

Dear Sphinx Themes Team,

Hope you are doing well. Thank you for your supporting and maintaining sphinx-themes. I was wondering if you are aware of any themes which allows full width content display and the contents display like gitbook. Here's a image to provide an instance. We want to utilise the space on the both sides (marked in red).

Thank you,
Yours Sincerely,
bitvijays

Implement a more graceful failure approach

It would likely be a good idea to change the render logic, to gracefully fail for themes that don't build properly, by printing out the information about them into the output and deploying it with that placeholder "it failed to render" messaging.

That would allow easier handling of cases like #70's breakages; pushing the responsibility to fix the theme-specific issues over to the theme authors more clearly.

How to add a new theme?

The instructions are not very clear. Step 3 says

PKG_NAME= <pass pkg-name> THEME= <pass theme name> make build run

Where?

I would like to add https://github.com/schettino72/sphinx_press_theme

PKG_NAME=sphinx_press_theme
THEME=press

Demo does not test/showcase ``.. content::`` directive

The demo document (more precisely src/demo.rst) does not showcase the ..contents:: directive.
The ..content:: directive is present but assigned the :local: parameter so that only headings in that section are reference.
However that section does not provide any further headings and as a result the .. contents:: directive does not provide any output.

Possible solutions:
a) Remove the :local: parameter, that way all headings of the entire document are collected, shown and referenced.
b) Add some (dummy) subheadings in the section of the ..contents:: directive, so these headings are collected and shown. In this case it might also be worth adding sub-sub-headings, so that the layout of nested sections in ..contents:: is observed.

Sidenote: It might or might not be worth adding :backlinks: none parameter to ..contents:: depending on what one wants to demonstrate.

If you like, I'll provide a pull request, though you must point out which solution you'll like to see.

Website is 404

When visiting https://sphinx-themes.org/, I get a 404 page from Github pages.

Numerous builds failing with Sphinx 7.0.0

Numerous theme builds are failing with Sphinx 7.0.0 - I've updated my theme to work with it and released the update to PyPI. How often are theme builds triggered to incorporate theme changes/releases?

Consider using something other than urllib.parse to demonstrate API docs? Plus dummy examples

The API docs for urllib.parse included in the theme demos don't feature a single method, only functions and classes without methods, so IMHO it's kind of a bad example to show what typical API docs will look like. Would you be open to using another module for the API docs demo and/or maybe adding some dummy class examples to that page manually?

The latter option would also be good because another thing that differentiates themes is how well they deal with overly long package/module or class/function names, e.g. Alabaster vs Insipid:

As such names are rare in Python's standard library, the only (?) way to get this to show would probably be dummy examples. Although maybe they should be on a separate page so people aren't put off themes just because of this edge case.

Thoughts?

PyData theme demo broken (build failed)

I believe that the PyData theme demo (https://sphinx-themes.org/sample-sites/pydata-sphinx-theme/) is broken, with the build error message ending with:

Theme error:
An error happened in rendering the page index.
Reason: KeyError('https://www.sphinx-doc.org')

Error in rendering pydata theme

The pydata theme is currently not rendering correctly:

New Theme: sphinx_documatt_theme

Hello, is it possible to add my "Documatt Theme"? It was originally for just my blog, but I open-sourced it recently.

package name is sphinx-documatt-theme, but html_theme is sphinx_documatt_theme.
PyPI: https://pypi.org/project/sphinx-documatt-theme/
real demo: https://blog.documatt.com/

Thanks!

Build against Sphinx pre-releases/development branches to help test theme compatibility/readiness

Follows from #114 -- it would be good to build websites with latest Sphinx prerelease and latest development branch of Sphinx, to provide meaningful information to the developers of themes and Sphinx.

/cc @AA-Turner -- do you think this would be meaningfully useful to Sphinx's maintainers?
/cc @humitos who has shown how to do this with a build of this site on RTD, in #114.

New theme: sphinx-wagtail-theme

Hi @pradyunsg !

Thanks for building sphinx-themes.org.

I think this site really needs the Wagtail theme represented (and featured, too, IMHO).

See:
https://sphinx-wagtail-theme.readthedocs.io/

I just saw that you have a contribution guide. I'd love to help but can't muster the time, even though it's a very good guide 👍

todo admonition is not displayed

In every documentation the todo admonition in kitchen sink is not visible.

Use stable Sphinx for building the "default" images

Hi! I'm opening this issue because of this comment from @pradyunsg

@humitos Those are themes being broken with Sphinx 6 (part of the goal with this site was to have it automatically test Sphinx pre-releases across themes). It's mildly concerning that alabaster is failing with Sphinx 6. :)

(from #113 (comment))

I think it's really good to build all the themes with the latest beta release from Sphinx because it helps developers to know if their theme is going to work once that version of Sphinx becomes stable. However, from a Sphinx's user perspective, it's not good to be pointed to this site to decide which theme to use and realize that some of them are broken.

Besides, from a marketing perspective, it's not good for the Sphinx ecosystem in general, to refer to this site as the canonical place to find really good themes and decide which one to use, but find there are some that are broken.

That said, I think it would be awesome if we could have two different versions of this site:

public facing using the latest stable release for Sphinx
developer facing using the latest beta release for Sphinx

I went ahead and tried this using Read the Docs:

Latest stable Sphinx:
- Public URL: https://sphinx-themes.readthedocs.io/en/latest/
- GitHub repository: https://github.com/humitos/sphinx-themes.org/tree/readthedocs
Latest beta Sphinx:
- Public URL: https://sphinx-themes.readthedocs.io/en/pre-sphinx/
- GitHub repository: https://github.com/humitos/sphinx-themes.org/tree/pre-sphinx
Project: https://readthedocs.org/projects/sphinx-themes/

I'm happy to rebase the commits and create a PR if you consider this work useful. If you like this work, but want to keep using GH pages to host the both versions, we can figure it out how to do it there as well. Let me know.

The Stanford demo is failing

Seems like https://sphinx-themes.org/sample-sites/stanford-theme/ is failing. The output says:

Could not install: stanford-theme

Not sure why, but I suppose it is because of the classifiers (see here), or maybe the build from source failed?

Links redirect

While running linkcheck, I found several redirects for links and image sources. PR incoming to fix links, but not images, as a new image source should be used instead, preferably a locally hosted static image.

kitchen-sink/generic.rst:31: WARNING: redirect  http://www.python.org/ - permanently to https://www.python.org/
kitchen-sink/generic.rst:31: WARNING: redirect  http://www.python.org - permanently to https://www.python.org/
kitchen-sink/lists.rst:192: WARNING: redirect  http://www.yahoo.com - permanently to https://www.yahoo.com/
kitchen-sink/generic.rst:6: WARNING: redirect  https://source.unsplash.com/32x32/daily?icon - with Found to https://images.unsplash.com/photo-1528944442442-099aa4e85b27?crop=entropy&cs=tinysrgb&fit=crop&fm=jpg&h=32&ixid=MnwxfDB8MXxyYW5kb218MHx8aWNvbnx8fHx8fDE3MTQ5ODE0ODQ&ixlib=rb-4.0.3&q=80&utm_campaign=api-credit&utm_medium=referral&utm_source=unsplash_source&w=32
kitchen-sink/generic.rst:271: WARNING: redirect  https://source.unsplash.com/200x200/daily?cute+puppy - with Found to https://images.unsplash.com/photo-1437957146754-f6377debe171?crop=entropy&cs=tinysrgb&fit=crop&fm=jpg&h=200&ixid=MnwxfDB8MXxyYW5kb218MHx8Y3V0ZSBwdXBweXx8fHx8fDE3MTQ5ODE0ODQ&ixlib=rb-4.0.3&q=80&utm_campaign=api-credit&utm_medium=referral&utm_source=unsplash_source&w=200
kitchen-sink/admonitions.rst:20: WARNING: redirect  https://www.sphinx-doc.org/ - with Found to https://www.sphinx-doc.org/en/master/
(reference/kitchen-sink/blocks: line  171) broken    http://someurl/release-0.1.0.tar-gz - HTTPConnectionPool(host='someurl', port=80): Max retries exceeded with url: /release-0.1.0.tar-gz (Caused by NameResolutionError("<urllib3.connection.HTTPConnection object at 0x104c34bc0>: Failed to resolve 'someurl' ([Errno 8] nodename nor servname provided, or not known)"))
make: *** [linkcheckbroken] Error 1

Add sorting

Right now this website is useful to get a comprehensive view of many Sphinx Themes. However, I suspect that the vast majority of people that land on the site are more interested in narrowing their list of possible Sphinx themes, rather than expanding it. The current number of themes, and large variability in quality, makes it really hard to get useful information from the website if you're trying to narrow down your search.

This process could be helped if there were basic abilities to re-order the themes in this list. For example, being able to do these alone:

Sort by GitHub stars
Sort by date last-updated
Sort by date created
Sort by date last-released

Would massively boost the signal-to-noise of the website (in my opinion, one of them might even be the default view). Is there any chance this functionality could be built into the site?

This is also related to #24 though I think would be much simpler to implement.

Thanks a lot !

sphinx-themes / sphinx-themes.org Goto Github PK

sphinx-themes.org's Introduction

Contributing

Acknowledgements

sphinx-themes.org's People

Contributors

Stargazers

Watchers

Forkers

sphinx-themes.org's Issues

Recommend Projects

Recommend Topics

Recommend Org

Jobs