-
Notifications
You must be signed in to change notification settings - Fork 1
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
New Column Based Documentation Style #20
Conversation
Starting work on a multi-columned layout for the docs. This is part of a push to ake `Docket` more generally useful for medium sized projects where documenttaiton is best arranged into folders rather than a single level of documentation.
Small tweak to the rendering of `<code>` to reduce the visual clutter, and add a small radius to the search box to soften it a little.
8fd5486
to
6222379
Compare
Documents outlining the proposed structure and behaviour of the new Docket design.'.
The baler is designed to allow lazy walking of trees.
Update bales to allow opening an unopened bale. Opening scans one level further into the directory tree. With this in place a POC lazy walk is now possible.
Move the argument parsing back from the legacy into the new codebase.
Move the search index builder and associated utilities back from legacy.
Bring the `Docket` back from the realms of `legacy/`. This just moves our walk bales into the docket for the time being. Proper rendering comes next..
Walk the items in each bale and render out by writing the raw markdown. Still needs work on the slug paths. Render context should hold the path rather than nav infos. Navigation doesn't render the root node yet either.
Still missing the main items. Feels like some of this job could be carried out by the render ctx.
Update the logging config to ensure our logging prefix doesn't clash with other tools'.
Abstract over the source of arguments so argument parsing can be tested.
Adds more design documents, and tweaks the behaviour of some parts of the new code. Still plenty of way to go. I'm getting more confident that this will pan out well though. That could just be coffee however.
|
||
/* Apply a dark color scheme */ | ||
@media (prefers-color-scheme: dark) { | ||
:root { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We'll want a JS toggle button for dark mode too. If it doesn't change the syntax scheme it should be fairly simple.
This is the start of the more abstract render pass. Renering will hopefully be decoupled from layout. Rendering will just be the process of walking the doctree and calling `render_page`. ``` state.ctx().layout().render_page(&writer, &state, &page)?; ``` Some shim renderable type may be needed to wrap pages and indices as is currently being done.
Navs are now fabricated _before_ the render state at each level. This means less context to pass into each render. Preparatory refactoring for introducing the `Layout` trait.
Introduces a `Layout` trait. This trait will be responsible for rendering items. A trait allows third party consumers to inject their own layouts if wanted. For now there is only the builtin layout. We could include the legacy layout for backwards compatibility this way.
src/doctree.rs
Outdated
} | ||
|
||
#[cfg(test)] | ||
mod test {} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Tests for bale opening would be super nice.
Add description for the older releases that were missed. Reformat a little.
Move to using a single `write` call, so the overall structure of the page is visible. For repeating elements we introduce shim renderables that perform the iteration for us. For the moment this is just the `Navs` renderable.
Remove any HTML specific code from the TOC. Renderables instead walk the public API of the `Toc` to perform the rendering. TODO: need to seal off the inner contents of the `Toc` and provide iterators for the elements and headings.
Hide the contents of the TOC, and provide an iterator API over the contents instead. This provides a better API separation between the doctree and the layout / rendering.
This should be all the main elements we want on each page ready for styling.
Might as well take advantage of the real estate.
Rescue the page's tests, and drop the remaining items in `legacy/`.
Bring back the sylesheets. Layouts can now have global assets. Include the js + style in the HTML layout. Things are now rendered with colours again!
Remove some junk colourschemes. Switch to a variable for the main font.
Properly layout the sidebars. Some fixes to the TOC to prevent them from looking quite as wacky. Fixup the line-heigh for _all_ content.
Title on the main doc page now that we render a TOC for all pages. This stops the main page of _our_ docs feeling so empty.
Add the javascript search back to the documentation pages.
Bring back the highlihter.
These weren't testing our stuff. Get rid.
Update rendering to correcty use relative paths for assets rather than baking in the paths based on `/`. This should mean documenation can be viewed from a sub-directory on a site again.
For syntect we need a shared lazy highlighter instance. This used to be held in a lazy_static macro defined variable. Switch to the more modern once-cell defined `Lazy` instead. This is preparatory for syntect itself moving away from lazy_static to once-cell for lazies too.
This is copied mainly from my blog. Still needs icons adding to the dark / light buttons. Plan is to use the Feather icons.
Update dark mode manual js toggle to use Feather icons instead of text.
Features:
TODO:
Fixes: #17