piccolo-orm/piccolo_theme

A clean and modern Sphinx theme.

piccolo_theme's Issues

Piccolo doesn't have appropriate CSS for list styles

When I have this in my source file:

1. Top-level
   a. second level
   b. second item second level
2. Second top level thing
   a. second second level
   b. second item second level

The intent is that in the rendered HTML I see uses numbers for the outermost list and lowercase letters in the second-level list.

The generated HTML has <ol class="arabic simple"> on the top-level list and <ol class="loweralpha simple"> on the second-level list.

If I use a style based on basic.css, those classes on the <ol> element result in the appropriate list-style being applied. However, using piccolo's basic_mod.css, the list-style CSS rules aren't applied, and in the rendered HTML all levels of the list use numbers.

Be able to set a custom logo

This will be shown in the nav bar.

pypi: no matching distribution found

Hi. First of all thank you for this great theme. It looks great.

I was trying to install the theme with pip, but I cannot manage to.
Even though the theme is advertised on pypi https://pypi.org/project/piccolo-theme/0.9.0/, it seems that it is not registered correctly.

To recreate, run the following:

$ python3 -m venv /tmp/env
$ source /tmp/env/bin/activate

# As listed on pypi
$ pip install piccolo-theme==0.9.0
Collecting piccolo-theme==0.9.0
  Could not find a version that satisfies the requirement piccolo-theme==0.9.0 (from versions: )
No matching distribution found for piccolo-theme==0.9.0

# As listed in https://piccolo-theme.readthedocs.io/en/latest/setup.html#install-piccolo-theme
$ pip install piccolo_theme  
Collecting piccolo_theme
  Could not find a version that satisfies the requirement piccolo_theme (from versions: )
No matching distribution found for piccolo_theme

fonts.googleapis.com alternative

When using the theme within China we noticed that fonts.googleapis.com is not working. Would it be possible for this theme not to use this url but include the font inside the theme like also is done for the default themes within mkdocs. see also mkdocs/mkdocs#1138

sphinx >= 7.2 appears to break `piccolo` theme

I upgraded to sphinx 7.2.2 and I now get this error (also happens with 7.2.0, 7.2.1 - seems to have been introduced in 7.2.x series):

writing output... [ 10%] docs/AUTHORS
Theme error:
An error happened in rendering the page docs/AUTHORS.
Reason: ThemeError("Local asset file paths must not contain query strings: '_static/basic_mod.css?v=0.7.0-1'")

If I revert to 7.1.2 and earlier, I don't encounter this error.

Feature request: setting to move `viewcode` source links to be right-aligned

Current situation: when using viewcode, source links appear immediately after the method declaration. This makes method declarations less readable, particularly when they include a return type.

Feature request: a togglable option to right-align these (or have it appear in the upper-right of the box)

Poor man's implementation (via custom.css)

span.viewcode-link {
    float: right;
}

Proposed user-facing toggle:

html_theme_options = {
    'right_align_source': True, //default false  
}

Add Playwright tests

We use Playwright to test other UI projects in the Piccolo ecosystem (see Piccolo Admin).

Playwright is a E2E / UI testing framework.

Phase 1

Approximate time needed: 1 to 2 hours, depending on existing knowledge of Playwright.

• Create a new folder called something like e2e.
• Create requirements/test-requirements.txt, containing Playwright and Pytest.
• Create a Playwright test (e.g. e2e/test_homepage.py), which performs some simple tests - e.g. loading the homepage, entering something into the search bar, and submitting it.
• Create scripts/run-tests.sh, which runs pytest.

Phase 2

Can be done in a separate PR.

Approximate time needed is 1 to 2 hours, depending on knowledge of GitHub actions.

• Run the tests using GitHub actions for a range of Sphinx versions (e.g. v4, v5), and Python versions.
  • Build the static files (cd docs && make html)
  • Have a Pytest fixture like this, which serves the static files. Hint, you should be able to use something like this, as a simple Python static file server.
• Save screenshots of the tests as build artefacts, so we can quickly check that the theme isn't broken on any Sphinx versions when reviewing a PR.

Declare if extension is safe for parallel reading

Doing a Sphinx build using multiple processes will complain:

WARNING: the piccolo_theme extension does not declare if it is safe for parallel reading, 
assuming it isn't - please ask the extension author to check and make it explicit
WARNING: doing serial read

setup(app) probably needs to return {'parallel_read_safe':True} but would it be set True or False?

Sphinx API docs

Re-enable PDF generation on Readthedocs

Building PDFs is failing in Readthedocs at the moment, which fails the entire build:

readthedocs/readthedocs.org#10150

Once resolved we need to uncomment these lines:

piccolo_theme/.readthedocs.yaml

Lines 15 to 17 in 220ccff

	# formats:
	# - pdf
	# - epub

Translating interface terms

I am looking for a way to translate properly interface term like: "Page contents", "Hide", "Search" etc. There is probably a way to do it with Sphinx, but I don't see why. I tryied with locales and shpinx but I don't have these terms.

I take any tip. Thanks.

Add GitHub link to header bar

A simple logo, which links GitHub.

Improved search styles

When searching, Sphinx uses some Javascript to dynamically add some highlights.

The styles need improving.

Dark mode in combination with group tabs is not readable

When using dark mode and group tabs the text inside the tabs is not visible

for an example see here

Feature request: Prevent sidebar collapse label:enhancement

Current situation: pages a level or more down in the Table of Contents are hidden unless viewed.

Feature request: configuration setting to show leaf-level table-of-contents entries by default (or n levels down)

Example user-facing implementation:
In conf.py,
html_theme_options = {
'toc_auto_minimize': True/False
//or
'toc_auto_minimize_level': 0 //default of zero
}

Add `Used By` section to `README`

@dantownsend , I recently noticed that Lance is using this theme on their website. Do you think it would be beneficial to include a Used By section in the README to showcase the projects using our theme?

Dark mode selection not global

Is there a setting that makes the dark mode selection global across all pages? For some reason it isn't working for me.

Improved table styles

The tables don't look great at the moment - just needs a simple border, and some more padding.

Code emphasis color in dark modes is not set - poor contrast.

I love the theme and am considering switching to it for a few of my projects!

One minor issue - it looks like the background color for emphasized code (HTML class hll) is not being overridden for dark modes. This results in some poor contrast.

For example:

Compared to light mode:

Dark/Light mode issue in code block

Hi. My system is configured to use dark mode by default:

But when I flip to the white theme, the text contained in the code block does not stay white:

and it only affects the non-colored text:

I'm using the latest piccolo-theme-0.5.1. I really like this theme, you've done a great job.

Sphinx 7.3: Quick search header is not hidden -> Header too big and hides main menu

Sphinx 7.3.x seems to have changed the syntax from <div id="searchbox" […]> to <search id="searchbox" […] which is not covered by Piccolo's CSS/SASS. The header's height becomes too big an therefor hides parts of the menu.

I think the following line

piccolo_theme/src/sass/basic_mod.scss

Line 150 in e22f783

div#searchbox {

has to be modified to something like

search#searchbox,
div#searchbox {
[…]
}

or just #searchbox?

Multiple colour themes

We could provide an option which sets the primary colour. It's currently blue, but we should be able to add green, orange etc.

The user can then specify the colour theme via html_theme_options.

html_theme_options = {
    "theme_color": "orange"
}

# Or let them specify an arbitrary colour primary colour
html_theme_options = {
    "theme_color": "#abc123"
}

This value will then be assigned to a CSS variable.

Improve autodoc style for 'breathe' entities

Hi there!

I am loving the python formatting for autodoc entries, so I would like to switch to this Sphinx theme. However, to keep things consistent, we also need to migrate the documentation of our C and C++ api's. They are generated with the 'breathe' python package. Sadly, they don't look so nice yet. I have looked at the js snippet that inserts the styles and
s in the right spots and I think it should be fairly straightforward to add a case for 'breathe' autodocs but I am not quite in the know on how this theme works, so before I dive in to try to do it myself I thought it post first.

Here is the html of a breathe generated function:

<dl class="cpp function">
   <dt class="sig sig-object cpp" id="_CPPv421dds_assert_liveliness12dds_entity_t">
      <span id="_CPPv321dds_assert_liveliness12dds_entity_t"></span>
      <span id="_CPPv221dds_assert_liveliness12dds_entity_t"></span>
      <span id="dds_assert_liveliness__dds_entity_t"></span>
      <span class="target" id="dds_8h_1a4face9db6e18ba6808bdbf7f4220209e"></span>
      <span class="n">
         <span class="pre">dds_return_t</span>
      </span>
      <span class="w"> </span>
      <span class="sig-name descname">
         <span class="n">
            <span class="pre">dds_assert_liveliness</span>
         </span>
      </span>
      <span class="sig-paren">(</span>
      <a class="reference internal" href="typedef_dds__basic__types_8h_1aa66538468c533a9ea558b7e280677b13.html#_CPPv412dds_entity_t" title="dds_entity_t">
       <span class="n">
         <span class="pre">dds_entity_t</span>
       </span>
      </a>
      <span class="w"> </span>
      <span class="n sig-param"> 
        <span class="pre">entity</span>
      </span>
      <span class="sig-paren">)</span>
      <a class="headerlink" href="#_CPPv421dds_assert_liveliness12dds_entity_t" title="Permalink to this definition">¶</a>
      <br />
   </dt>
   <dd>
      <p>This operation manually asserts the liveliness of a writer or domain participant. </p>
      <p>This operation manually asserts the liveliness of a writer or domain participant. This is used in combination with the Liveliness QoS policy to indicate that the entity remains active. This operation need only be used if the liveliness kind in the QoS is either DDS_LIVELINESS_MANUAL_BY_PARTICIPANT or DDS_LIVELINESS_MANUAL_BY_TOPIC.</p>
      <dl class="field-list simple">
         <dt class="field-odd">Parameters</dt>
         <dd class="field-odd">
            <p><strong>entity</strong> – <strong>[in]</strong> A domain participant or writer</p>
         </dd>
         <dt class="field-even">Return values</dt>
         <dd class="field-even">
            <ul class="simple">
               <li>
                  <p><strong>DDS_RETCODE_OK</strong> – The operation was successful. </p>
               </li>
               <li>
                  <p><strong>DDS_RETCODE_ILLEGAL_OPERATION</strong> – The operation is invoked on an inappropriate object. </p>
               </li>
            </ul>
         </dd>
         <dt class="field-odd">Returns</dt>
         <dd class="field-odd">
            <p>A dds_return_t indicating success or failure.</p>
         </dd>
      </dl>
   </dd>
</dl>

Let me know if you're interested in adding support for my usecase. Cheers!

Lists - unreadable black elements in Dark mode

Hello,

It seems the Dark mode is not fully readable with some HTML elements. As an example, various kind of lists (Definition list, Option list, Field list, etc.) are rendered with a black main item in Dark mode. See an example here: https://sphinx-themes.org/sample-sites/piccolo-theme/kitchen-sink/lists/#field-list

Improve header bar on mobile

Replace the search bar in the header bar when on mobile, with a search icon which opens a popup.

Dark mode

A simple toggle switch in the header or footer.

Mathjax overlaps sidebar on mobile

When opening the navigation menu on a mobile device, Mathjax overlaps the sidebar causing the sidebar to become unreadable.

Example:

Update `doc-requirements.txt` to use Sphinx 6

We can't currently upgrade Sphinx to version 6 in requirements/doc-requirements.txt because Breathe only supports Sphinx 5.

Waiting on this:

breathe-doc/breathe#884

Setup GitHub actions

So we can release via GitHub. Like this:

https://github.com/piccolo-orm/piccolo/blob/master/.github/workflows/release.yaml

Add to sphinx-themes.org

Need to do a PR, following the instructions here.

requirements.txt is not packaged in the tarball

Your setup.py file requires processing the requirements.txt file but it is not present in the source tarball.

    File "setup.py", line 36, in <module>
      install_requires=parse_requirement("requirements.txt"),
    File "setup.py", line 17, in parse_requirement
      with open(os.path.join(directory, "requirements", req_path)) as f:
  FileNotFoundError: [Errno 2] No such file or directory: '/home/conda/staged-recipes/build_artifacts/piccolo-theme_1645472732392/work/requirements/requirements.txt'