New Column Based Documentation Style #20

iwillspeak · 2022-06-26T10:16:17Z

Features:

Light and dark colourschemes
Improved search layout
Grid-based layout
Responsive layout + font sizes.

TODO:

Dark mode support.
Update typography.
Sticky TOC + Nav.
Finalise Nav content.

Fixes: #17

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.

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.

iwillspeak · 2022-07-17T09:34:07Z

assets/style.css

+
+/* Apply a dark color scheme */
+@media (prefers-color-scheme: dark) {
+	:root {


We'll want a JS toggle button for dark mode too. If it doesn't change the syntax scheme it should be fairly simple.

src/asset.rs

src/baler.rs

src/docket.rs

src/legacy/docket.rs

src/legacy/mod.rs

src/legacy/page.rs

src/search.rs

The plan for the doctree is to merge bales and pages together into a single tree. Hopefully we can then seprate out their shared concerns (navigation).

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

iwillspeak · 2022-07-17T17:47:05Z

src/doctree.rs

+}
+
+#[cfg(test)]
+mod test {}


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.

Three column style first cut.

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.

iwillspeak · 2022-08-09T07:46:45Z

This might be the better option for the search box placement:

iwillspeak added the Feature label Jun 28, 2022

iwillspeak added this to the 10 milestone Jun 28, 2022

iwillspeak added 3 commits July 15, 2022 07:42

Initial Multi-Columned Layout

512338c

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.

Style Tweaks

d835299

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.

Remove Background from Left Column

6222379

iwillspeak force-pushed the feature/newstyle branch from 8fd5486 to 6222379 Compare July 15, 2022 06:43

iwillspeak added 13 commits July 15, 2022 08:15

Reformatting Things

69aa6e4

Add some Design documents

f46acb4

Documents outlining the proposed structure and behaviour of the new Docket design.'.

Initial Baler Implementation

35da556

The baler is designed to allow lazy walking of trees.

Walkable Bales

d34c979

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.

Pull Argument Parsing from Legacy

b251385

Move the argument parsing back from the legacy into the new codebase.

Retrieve Search from Legacy

1170edf

Move the search index builder and associated utilities back from legacy.

Revive Docket

3ef1443

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..

Initial Bale Walk Render

3ac2912

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.

Proper Prefixes on Nav Items

75b2227

Still missing the main items. Feels like some of this job could be carried out by the render ctx.

Custom env_logger Configuration

2b15bbc

Update the logging config to ensure our logging prefix doesn't clash with other tools'.

Argparse Tests

a2d569b

Abstract over the source of arguments so argument parsing can be tested.

A Whole Buncha Design Thinking

ec0945d

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.

Actually Use the Example Asset

a2d3ff8