Claude/plottle audit gate2 UI docs - #24
Merged
Merged
Conversation
…fixes
Audit A-17, A-18, A-19, A-25, A-29, A-30, A-35.
New module plottle/utils/theming.py owns theme reading, writing and CSS
generation, because none of the three theme defects could be fixed in place.
A-17 -- Home.py injected a stylesheet with the NCCU dark palette baked in as
literals while Settings let the user change the theme, and nothing connected
them. On a light theme the hero subtitle was white-on-white and the scrollbar
stayed black. Two of those literals also disagreed with each other -- the hero
subtitle assumed a dark background, _ADV_HEADER used Streamlit's *light* grey --
so one was always low-contrast whatever theme was active, including the shipped
dark default. app_css() now derives every colour from the live theme via
st.get_option("theme.*"), which reflects the merged config actually in effect
rather than just the file.
A-18 -- the Settings page resolved config.toml relative to the package, returned
silently when it did not exist, and printed "Theme saved" regardless. That silent
path was the default for every pip-installed user, since the wheel does not ship
.streamlit/. Two fixes: the target is now $CWD/.streamlit/config.toml, which is
where Streamlit actually looks and works for both source checkouts and installs;
and write_theme raises OSError so the caller reports the truth. Verified end to
end through AppTest -- a writable directory gets a real file and a success
message naming the path; a failing write gets an actionable error and no success
message.
A-19 -- the old writer re-serialised the whole file from parsed TOML, destroying
every comment (including the NCCU palette documentation), silently dropping
non-dict top-level values, and emitting Python repr for lists, which is invalid
TOML. write_theme now rewrites only the [theme] key lines, preserves comments
inside and outside the table, leaves other sections byte-identical, and writes
atomically via tempfile + os.replace so an interrupted save cannot truncate the
config.
A-29 -- restored the sidebar collapse control, which was CSS-hidden and locked
the sidebar open, costing plot canvas width on small screens and at high browser
zoom. Added alt text to all four base64 <img> tags; the two NCCU images are
institutional branding, exactly the content that needs a text equivalent.
A-35 -- dropped the Google Fonts <link>. It failed on an air-gapped lab machine,
disclosed a third-party request on every load, and Streamlit does not reliably
preserve <link> elements passed through st.markdown, so it may never have loaded
at all. The local font stack was already the fallback.
A-30 -- Data Tools (434 lines implementing the 12 documented DataFrame ops) had
no sidebar link. With st.navigation(position="hidden") the sidebar is the only
navigation, so the page was reachable only by typing its URL.
A-25 -- "26 plot types" corrected to 27 in eight places. tests/test_docs_
consistency.py derives the expected count from PLOT_TYPES rather than hardcoding
it, so adding a plot type and forgetting the docs fails, and updating both
passes with no test change. It also caught my own wrong assumption that there
were only three plot categories -- there is a fourth, Specialty, holding
inset_plot.
Note the Settings page imports theming.get_config_path aliased: unaliased it
shadowed user_settings.get_config_path and silently repointed the "Config File"
section from config.json to config.toml.
1006 passed, 21 skipped. ruff, ruff format and mypy clean. All three edited pages
render with zero exceptions under streamlit.testing.v1.AppTest.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013YLgSnkyRUosy5sxWUb33P
Per the user's decision: drop Sphinx, wire up index.html. docs/ held two disconnected systems. A full Sphinx setup -- conf.py, index.rst, api/*.rst, Makefile, furo, a `docs` extra -- that no workflow ever built, and a hand-written index.html. docs.yml uploaded ./docs/ raw, so the published site was one marketing page: the .rst sources shipped as dead files, the API reference was never generated at all, and the seven markdown guides shipped as raw .md that browsers download rather than render. index.html linked to none of them -- five in-page anchors and four GitHub links, nothing into docs/. Sphinx removed (conf.py, index.rst, api/, Makefile, _static/, _templates/), and the docs extra now pins `markdown` instead of sphinx+furo. New build_docs.py renders each guide into a page styled to match index.html, with a shared nav, breadcrumb, and footer. It rewrites cross-references from `tutorials/cli_guide.md` to the built .html, and wraps every table in an overflow-x container so a wide reference table cannot make the page scroll sideways. docs.yml installs markdown, runs the build, and uploads docs/_site/. .nojekyll moved into docs/ where it is actually part of the artifact. index.html gains a Documentation section with a card per guide plus a nav link, so every page is reachable from the landing page. Rendering the site in Chromium caught what grep had not: the guides still taught the old namespace. getting_started.md and cheatsheet.md were full of `from modules.io import ...`, which has not existed since the rename -- the A-24 problem, still live in the guides after the README was fixed. Also stale and now corrected in getting_started.md: - install step said `pip install -r requirements.txt`, which no longer installs the package or the `plottle` command - "GUI Pages at a Glance" listed six pages ending at "6 - Settings", left over from the pre-M21 structure that TDEC-001 flagged for the README in March - Next Steps pointed at notebooks/ (excluded per TDEC-007, does not exist), DEPLOYMENT.md (excluded per G-007, does not exist), and "the course discussion board", which does not belong in a public repo Navigation verified by clicking through in Chromium: nav links, logo, and all six landing-page cards resolve, no page overflows horizontally at 1280px or 390px, and no JS errors. Also in this commit: - A-25 finished. My earlier sed was case-sensitive and missed "26 Plot Types" in an index.html card heading and a Help page header. The guard test was case-sensitive too, so it had been passing vacuously over both -- now IGNORECASE, and it fails on either. - A-27: removed the dead [tool.pytest.ini_options] block. pytest.ini takes precedence, so it was inert, and it declared a `visualization` marker that pytest.ini does not -- under --strict-markers anyone following it would error. - tests/test_docs_site.py: 17 tests. The most useful asserts that every markdown guide under docs/ is either in build_docs.PAGES or under docs/archive/, so a guide added later cannot ship unreachable the way these seven did. - ruff --fix removed genuinely unused imports from four test files. Not done here: the remaining 30 ruff findings in tests/ and examples/ (A-28). That wants to be its own mechanical commit alongside widening the CI lint scope. 1023 passed, 21 skipped. ruff, ruff format and mypy clean. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013YLgSnkyRUosy5sxWUb33P
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request modernizes and simplifies the documentation build system, replacing the legacy Sphinx-based approach with a new Python script, and updates references throughout the documentation to reflect current APIs and features. It also corrects and updates documentation content to match recent code changes.
Documentation build system overhaul:
docs/Makefile,docs/_static/.gitkeep,docs/_templates/.gitkeep,docs/api/io.rst,docs/api/math.rst,docs/api/plotting.rst). [1] [2] [3] [4] [5]build_docs.pyscript that builds the static documentation site by rendering markdown guides into styled HTML pages, wiring them together with navigation, and copying assets. This script replaces Sphinx and is now the single source of truth for documentation builds..github/workflows/docs.yml) to use the new script: it now sets up Python, installs the markdown package, runsbuild_docs.py, and uploads the generated site fromdocs/_site/. [1] [2]Documentation content and API updates:
README.mdanddocs/cheatsheet.mdto reflect the current API namespace (plottle.*instead ofmodules.*), and increased the reported number of plot types from 26 to 27. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11]These changes streamline the documentation workflow, ensure the published site is complete and up-to-date, and improve the consistency and accuracy of API references for users.