Code Monkey home page Code Monkey logo

boostlook's Introduction

BoostLook

This is a set of stylesheets, templates, and code for Asciidoctor and Antora rendered documentation to give it a uniform look and feel befitting the quality of Boost.

Example of integration into a doc Jamfile:

html mp11.html : mp11.adoc
    :   <use>/boost/boostlook//boostlook
        <dependency>mp11-docinfo-footer.html
    ;

Noto font files are covered under the Open Font License:

https://fonts.google.com/noto/use

Live Preview for AsciiDoc Documentation

BoostLook includes a live preview feature to streamline local development and review of AsciiDoc documentation. This allows for automatic rendering and real-time browser preview of changes made to specimen.adoc and boostlook.css files.

Overview

The preview functionality is handled by a Ruby script (boostlook_preview.rb). This script monitors AsciiDoc, HTML, and CSS files for changes, automatically rebuilding and opening the rendered HTML in your default web browser.


Prerequisites

Ensure the following dependencies are installed:

  • Ruby (>= 2.7 recommended)
  • Asciidoctor – Install via gem install asciidoctor
  • Listen Gem – Install via gem install listen
  • Boost.Build (b2) – Required for builds invoked by the script. Ensure it is installed and available in your system's PATH.

Usage and Detailed Steps

  1. Install Ruby and Required Gems:

    • Ensure Ruby is installed on your system. You can check by running:
      ruby -v
      If Ruby is not installed, follow the instructions on ruby-lang.org to install it.
    • Install Asciidoctor:
      gem install asciidoctor
    • Install the Listen gem:
      gem install listen
  2. Install Boost.Build (b2):

    • Follow the instructions on the Boost.Build website to install b2.
    • Ensure b2 is available in your system's PATH by running:
      which b2
  3. Locate Specimen AsciiDoc File:

    • Place your AsciiDoc files in the doc directory. The default file is doc/specimen.adoc.
    • The default file structure should include:
     /boostlook
       ├── doc
       │   └── specimen.adoc <--
       │   └── ...
       ├── boostlook.css
       └── boostlook_preview.rb
       └── boostlook.rb
       └── ...
    
  4. Navigate to the project directory:

    cd /path/to/boostlook
  5. Run the preview script:

    • Ensure you're in the root folder
    ruby boostlook_preview.rb
  6. Edit and Preview:

    • Edit your AsciiDoc (specimen.adoc) or CSS (boostlook.css) files.
    • The script will automatically detect changes and rebuild the documentation.
    • Refresh the browser to see changes.
  7. Refresh Your Browser to view changes.


Troubleshooting

  • Script Not Running:

    • Ensure all prerequisites are installed correctly.
    • Check for any error messages in the terminal and resolve them accordingly.
  • Changes Not Reflecting:

    • Ensure the files being edited are within the monitored directories (doc and root directory).
    • Verify that the browser is refreshing automatically or manually refresh the browser.
  • Boost.Build (b2) Not Found:

    • Ensure b2 is installed and available in your system's PATH.
    • Run which b2 to verify its availability.

boostlook's People

Contributors

julioest avatar cdw9 avatar vinniefalco avatar rbbeeston avatar mborland avatar grafikrobot avatar sdarwin avatar

Stargazers

 avatar

Watchers

Marshall Clow avatar Emil Dotchevski avatar Louis Tatta avatar Dmitry Arkhipov avatar  avatar  avatar Richard Hodges avatar Alan de Freitas avatar Christian Mazakas avatar Peter Turcan avatar Spencer Strickland avatar  avatar

boostlook's Issues

Phase 1 work on boostlook UI

This is a placeholder for the first batch of work on the boostlook UI, and will likely encompass wide ranging fixes to font sizes, spacing and such. Details should be provided in the PR.

As PR are approved, new, more specific tasks will follow.

align code styling between doc types

styling for code blocks inconsistent between boostbook, antora, asciidoc etc.

Each styling pattern will need to be decoded and align so they match.

Change font name

in boostlook some fonts are not loading, and the em tag is using an algorythmic italic

Please update font name "Noto Sans Italic" to "Noto Sans Display" so it uses the italic font as part of the normal font.

Also check that in the standalone viewer that the fonts are being loaded

Update GitHub Action to Trigger Action on website-v2-docs

Add an action that triggers a workflow in the website-v2-docs repository whenever the develop branch is updated. This ensures the latest boostlook.css is fetched automatically, keeping the website documentation consistently up-to-date with the most recent styles and changes.

collapse nav UI should not move when toggled

For the navigation visibility button:

image

The collapsed / expanded version of the page should place the button in the same spot. It should be possible to click repeatedly to toggle the side nav, without moving the mouse. Let's see some proposed ideas in this issue first and then choose.

feature: preview tool

It would be nice to have a command line tool which, when invoked, renders the specified asciidoc input file into HTML using boostlook, and opens the result in a browser window.

fixed antora menu on mobile

on mobile the toolbar menu on mobile is scrolling rather than fixed to the top. needs the following:
.toolbar {
...
width: 93%;
position: fixed;
top: 0;
padding-top: 10px;
}

Image

Prevent hyphenation of entity links generated by MrDocs

Links to C++ entities are currently subject to be split across several lines through hyphenation. For example:

Image

Live: https://anarthal.github.io/mysql-mrdocs-v1/mysql/reference/boost/mysql/sequence.html (please ignore the other glitches, they're in the process of being solved).

Breaking the name of a C++ entity looks weird, as it's not legal in C++. Entity names should be limited in number of characters, so it should be safe to apply whatever CSS property is required to make the word be entirely on the next line.

TOC Styling updates

  • Reduce the level of bolding
  • Subheadings should not be bold
  • All links should display as the text default black color
  • Links should change to blue on hover
Image

Code Highlighting sample sheet

There needs to be a sample specimen doc with different code blocks using the different code types used within the projects as a basic standard for how a block should look when using highlightjs, in both light and dark mode

Will also need a way to create a gulp preview

Create adoc for boostlook testing

Boostlook needs a CI setup where on PR or push to master/develop it renders the sample.adoc into HTML and publishes it, so at any time we can look at the master or develop rendering and know what the latest style looks like.
../../../b2 cxxstd=20 toolset=gcc-13 define=BOOST_CHARCONV_RUN_BENCHMARKS STL_benchmark linkflags="-lfmt" -a release .
needs to go into a code block and we want to see that in the sample.adoc

This sample should include all options used in the adoc.

process for rebuilding all effective docs when boostbook changes

When someone renders asciidoctor docs, the boostlook.css file contents need to be inserted. This is accomplished by passing the right command line argument to the asciidoc tool, as shown here:
https://github.com/vinniefalco/mp11/blob/develop/doc/Jamfile#L13

When someone renders antora docs, the same thing should happen. The boostlook.css file contents should be inserted into the resulting HTML

The website injects the header when it serves documentation. And we should modify the asciidoc and antora build process so that the resulting HTML has a hint to where the website should insert the header

Boostlook support and updates of antora docs

Multiple antora issues, fix in boostlook where possible:

  1. Sidebar fonts should be condensed and vertically spaced more closely.
  2. Sidebar links- remove underline, font text black, hover make blue (from standard colors)
  3. Sidebar selected item - have carat text to item, without indenting item
  4. Breadcrumbs - condensed font, move home icon from right to the beginning of breadcrumb.
  5. Breadcrumbs missing on mobile view
  6. Add "printable version"
  7. Code syntax highlighting needed
  8. Tables need boostlook appearance

heading oddity

Noticed this in the "Any" library h1 header on stage. Seems like #LibraryReadMe h1 a was throwing it off with the float:right, can you take a look?
It should be at the top and left justified.
Image

Phase 4 UI

The specific goal for this phase has several components:

  1. we want to refactor font related tags and classes into single tag level classes that apply the same everywhere, for example taking:
.boostlook h4 {
    font-size: 130%;
}

.boostlook .antora h4 {
     font-size: 125%;
    font-weight: bold;
     margin-left: 1rem;
}

should be :

.boostlook h4 {
    font-size: 130%;
    font-weight: bold;
}

.boostlook .antora h4 {
     margin-left: 1rem;
}

move the font related elements together and the specifics on formatting for a specific case separately. This will simplify the code and insure that fonts will display the same under any doc type.

  1. Any references to font weights should be number values based on the variable fonts, so I'd like to start with 500 and go bolder at a +50 increments

  2. Be sure all border-radius attributes are removed or set to zero.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.