Skip to content

Latest commit

 

History

History
131 lines (101 loc) · 5.02 KB

README.md

File metadata and controls

131 lines (101 loc) · 5.02 KB

Monocle

Overview

Monocle is a Makefile visualizer for the web.

You can use it to view a Makefile as a graph of its targets and their dependencies—in your web browser.

Limitations

Monocle has the following limitations:

  • It only parses a single Makefile (i.e. it does not follow include paths).

Technologies

Monocle is built upon the following technologies:

This code base was bootstrapped by running:

npx --yes create-vite monocle --template react-ts

The originally-generated README.md file has been archived to README.bak.md.

Favicon

The favicon (public/favicon.ico) was generated by favicon.io, using the following settings:

  • Text: m
  • Background: Rounded
  • Font Family: Leckerli One
  • Font Variant: Regular 400 Normal
  • Font Size: 110
  • Font Color: #FFFFFF
  • Background Color: #212529 (i.e. the same color as Bootstrap's dark theme background; i.e. --bs-body-bg)

Development

Prerequisites

  • Node 20 is installed

Quick start

  1. Install NPM dependencies
    npm install
  2. Start development server
    npm run dev
  3. Visit: http://localhost:5173/monocle/

Testing

npm test

Tests are written using Vitest.

Formatting code

npm run prettier

Patches

There are two types of patches in this repository:

  1. Those managed manually (these are all in src/patches/)
    1. src/patches/@kba/makefile-parser/index.d.ts: TypeScript information for the @kba/makefile-parser JavaScript package
  2. Those managed using patch-package (these are all in patches/)
    1. patches/mdx-mermaid+2.0.0.patch: A patch file to work around the TypeScript#52363 issue for the mdx-mermaid package

The file, patches/mdx-mermaid+2.0.0.patch, was generated by performing the following steps:

  1. Add "postinstall": "patch-package" to package.json's scripts object
  2. Edit node_modules/mdx-mermaid/package.json (as documented in the patch file)
  3. Run $ npx patch-package --exclude '^$' mdx-mermaid to generate the patch file

Deployment

Quick start

  1. Bump version number in package.json and package-lock.json
    # Alternatively, you can specify `major` or `minor` instead of `patch`.
    npm version --git-tag-version false patch

    The version number will accessible via PACKAGE_VERSION at build time (more info)

  2. (Optional) Generate and preview the production build
    npm run build
    npm run preview

    Then visit: http://localhost:4173/monocle/

  3. Generate and deploy a production build
    npm run deploy

Roadmap

  1. Apply syntax highlighting to the Makefile content (non-React example)
  2. Allow the user to load a Makefile by entering its URL into a textbox (users can already enter it via query string)
  3. Allow the user to upload a Makefile by browsing for it on their computer (users can already drag-and-drop one)
  4. Allow user to choose the graph direction (TB versus LR) (users can already copy then edit the Mermaid code)
  5. Allow user to choose whether to download "light" or "dark" diagram, regardless of current website theme
  6. Style targets and non-targets distinctly from one another in the diagram
  7. Implement a mode optimized for viewing (the diagram of) a Makefile loaded from a URL specified via query params
  8. Maybe: Store current Makefile in browser storage (refreshing the page currently discards the Makefile content)
  9. Maybe: Add SVG pan and zoom

FAQ

  • Q: Why'd you name it "monocle?"
  • A: I went with the word "monocle" because its "m", "k", and "l" sounds are in the same order as in the word "Makefile", and a monocle is a thing people use to see things in a different way.