🎨 Update docs theme and add tutorial #1184

chrisjsewell · 2024-05-27T08:54:07Z

Update the theme to furo and colors to match new branding
- branding coloring loosely based on https://mintlify.com/docs/quickstart
Restructure toc-trees, to make the documentation easier to navigate
Improve landing page
- Improve top "hero" section
- Add feature section
- move examples to tutorial
Add tutorial page, with worked example covering most directives
- took some things from https://sphinx-needs-demo.readthedocs.io

See: https://sphinx-needs--1184.org.readthedocs.build/en/1184/

codecov · 2024-05-27T08:58:35Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 86.44%. Comparing base (1de1a7a) to head (212d955).
Report is 91 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1184   +/-   ##
=======================================
  Coverage   86.44%   86.44%           
=======================================
  Files          56       56           
  Lines        6501     6501           
=======================================
  Hits         5620     5620           
  Misses        881      881

Flag	Coverage Δ
pytests	`86.44% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

docs/tutorial.rst

danwos

Thanks for the changes.
Haven't done a full review yet, but I noticed that "useblocks" is not written always in the same way.
Sometimes it's "UseBlocks" or "Useblocks".
But it should be in all cases "useblocks" :)

danwos · 2024-08-06T07:09:38Z

It looks like the upper border is missing on need objects:

Deactivating this CSS property make it look beautiful:

In this case, we also get some border-radius, which looks nice:

danwos

Great work, like the changes a lot.

Have 1-2 findings.

danwos · 2024-08-06T07:20:26Z

docs/directives/index.rst

 .. toctree::
+   :caption: Need creation


I would remove the caption, or set it as sub-title in front of "Directives for creating and modifying needs:"

Currently, it looks like we have two introductions to the toc table:

danwos · 2024-08-06T07:23:22Z

docs/_static/flow_chart.svg

This file looks damaged.
Downloading and opening this gives me this error:

danwos · 2024-08-06T07:28:12Z

docs/filter.rst

+         Python 2.7 environment.
+
+
+.. need-example:: Filter result as table*


I guess the * is not needed

danwos · 2024-08-06T07:28:28Z

docs/filter.rst

+
+.. need-example:: Filter result as diagram
+
+   .. needflow::


This example has no results.

danwos · 2024-08-06T07:49:56Z

docs/tutorial.rst

+        :columns: id,type,title,status
+        :style: table
+
+The default style for the table is a simple HTML table, but we can also use the ``datatables`` style to add dynamic pagination, filtering and sorting,


I think the default style is the datatables style, or have this changed?

nope you are correct, now fixed

chrisjsewell · 2024-08-06T08:50:14Z

It looks like the upper border is missing on need objects:
Deactivating this CSS property make it look beautiful

can you confirm what browser (and what version) you are using @danwos; I don't see this for either firefox (mac arm64 128.0.3) or chrome (mac arm64 127.0.6533.89), and you definitely need border-collapse to make the inner borders show:

chrisjsewell · 2024-08-06T08:58:59Z

But it should be in all cases "useblocks" :)

fixed

chrisjsewell · 2024-08-06T10:19:18Z

I don't see this for either firefox (mac arm64 128.0.3) or chrome (mac arm64 127.0.6533.89)

Ok @danwos, this is where it gets weird....

when I view the page on my MacBook monitor, it all looks fine (for Firefox/Chrome)
BUT, when I look at the page on my external monitor, I see the same as you!

So perhaps its something to do with the screen resolution and the width of the lines 😅🤷 (my MacBook monitor has a lot better resolution)

edit: indeed when I change all the border thicknesses from 1px to 2px, you can now see them again

chrisjsewell · 2024-08-06T20:36:08Z

It looks like the upper border is missing on need objects:
Deactivating this CSS property make it look beautiful

Ok this should be fixed now; by removing the table row border. As mentioned above, your fix of removing the border-collapse I do not believe is a solution, because it means you cannot add "internal" borders.

I agree it would be nice to have rounded edges, but will look at that probably in a later PR

danwos · 2024-08-12T13:03:05Z

Thanks THanks for the fixes.

I detected another small border-issue:

Source: https://sphinx-needs--1184.org.readthedocs.build/en/1184/tutorial.html#T_CAR

The bottom left border of the sidebar is missing.
All the other borders and the standard Needs are looking fine.

danwos

see last comment

chrisjsewell · 2024-08-14T13:01:59Z

Ok @danwos 212d955 should fix it (and add a border-radius)

I have checked the documentation for all the themes and looks to be working for all (alabaster, sphinx_rtd_theme, furo, sphinx_immaterial, pydata_sphinx_theme)

chrisjsewell changed the title ~~👌 Multi-theme support~~ 🎨 Update docs theme May 27, 2024

chrisjsewell force-pushed the new-doc-theming branch 5 times, most recently from 716fbf7 to fe6ed55 Compare June 3, 2024 07:35

chrisjsewell changed the title ~~🎨 Update docs theme~~ 🎨 Update docs theme and add tutorial Jun 3, 2024

chrisjsewell force-pushed the new-doc-theming branch 2 times, most recently from 06444a9 to 74e25e1 Compare June 3, 2024 07:48

chrisjsewell force-pushed the new-doc-theming branch 2 times, most recently from 1f82ced to 24e8971 Compare June 13, 2024 11:58

chrisjsewell marked this pull request as ready for review June 28, 2024 17:38

chrisjsewell added 6 commits June 28, 2024 19:40

🎨 Update docs theme

61596ba

Re-organise docs

4b8c754

Start to add tutorial

b9fe55f

Update intro page

5057c01

simplify furo color vars

62f1d91

add "next steps" to tutorial

4d6df08

chrisjsewell force-pushed the new-doc-theming branch from ac8a938 to 4d6df08 Compare June 28, 2024 17:40

Update test-collapse-button.cy.js

efa1e21

chrisjsewell requested a review from danwos June 28, 2024 18:35

add link

cc55bcf

chrisjsewell commented Jun 28, 2024

View reviewed changes

docs/tutorial.rst Outdated Show resolved Hide resolved

chrisjsewell added 5 commits June 29, 2024 01:05

Update docs/tutorial.rst

b2389e0

final additions

fa18360

Update conf.py

f526fab

fix tests

fce3beb

Update tutorial.rst

1fc8db8

danwos requested changes Aug 6, 2024

View reviewed changes

chrisjsewell added 3 commits August 6, 2024 09:52

fix flow chart svg

2cb0a2d

fix typo

754db79

ensure all useblocks lower case

6fe0685

fix css typo

ac793f5

chrisjsewell added 2 commits August 6, 2024 21:29

fix need table borders

6fdd264

Update tutorial.rst

ec36cd8

chrisjsewell added 2 commits August 6, 2024 21:51

fix Filter result as diagram

abc3beb

remove directive toc captions

33ec9ac

chrisjsewell requested a review from danwos August 6, 2024 20:53

danwos requested changes Aug 13, 2024

View reviewed changes

Use border-collapse separate

212d955

chrisjsewell requested a review from danwos August 14, 2024 13:02

danwos approved these changes Aug 14, 2024

View reviewed changes

chrisjsewell merged commit 2045121 into master Aug 14, 2024
21 checks passed

chrisjsewell deleted the new-doc-theming branch August 14, 2024 13:07

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🎨 Update docs theme and add tutorial #1184

🎨 Update docs theme and add tutorial #1184

chrisjsewell commented May 27, 2024 •

edited

Loading

codecov bot commented May 27, 2024 •

edited

Loading

danwos left a comment

danwos commented Aug 6, 2024 •

edited

Loading

danwos left a comment

danwos Aug 6, 2024

chrisjsewell Aug 6, 2024

danwos Aug 6, 2024

chrisjsewell Aug 6, 2024

danwos Aug 6, 2024

chrisjsewell Aug 6, 2024

danwos Aug 6, 2024

chrisjsewell Aug 6, 2024

danwos Aug 6, 2024 •

edited

Loading

chrisjsewell Aug 6, 2024

chrisjsewell commented Aug 6, 2024

chrisjsewell commented Aug 6, 2024

chrisjsewell commented Aug 6, 2024 •

edited

Loading

chrisjsewell commented Aug 6, 2024

danwos commented Aug 12, 2024 •

edited

Loading

danwos left a comment

chrisjsewell commented Aug 14, 2024

		Python 2.7 environment.


		.. need-example:: Filter result as table*

🎨 Update docs theme and add tutorial #1184

🎨 Update docs theme and add tutorial #1184

Conversation

chrisjsewell commented May 27, 2024 • edited Loading

codecov bot commented May 27, 2024 • edited Loading

Codecov Report

danwos left a comment

Choose a reason for hiding this comment

danwos commented Aug 6, 2024 • edited Loading

danwos left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

danwos Aug 6, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrisjsewell commented Aug 6, 2024

chrisjsewell commented Aug 6, 2024

chrisjsewell commented Aug 6, 2024 • edited Loading

chrisjsewell commented Aug 6, 2024

danwos commented Aug 12, 2024 • edited Loading

danwos left a comment

Choose a reason for hiding this comment

chrisjsewell commented Aug 14, 2024

chrisjsewell commented May 27, 2024 •

edited

Loading

codecov bot commented May 27, 2024 •

edited

Loading

danwos commented Aug 6, 2024 •

edited

Loading

danwos Aug 6, 2024 •

edited

Loading

chrisjsewell commented Aug 6, 2024 •

edited

Loading

danwos commented Aug 12, 2024 •

edited

Loading