doc.adoc

Doc

Table of Contents

• page
• help
• ws
• more
  • blog posts
  • high-level
  • in japanese
  • podcasts
  • python tool
  • slack
  • videos
  • workspaces

The poly tool includes a doc command to open web-based documentation. The shell's autocompletion support makes listing and accessing different parts of the documentation a breeze, so go ahead and start one up:

poly

Run the doc command to open the start page of the poly tool documentation:

example$ doc

Tip	The example$ prompt shows that we are working from our tutorial example workspace, but you can experiment with the doc command from any workspace.

You should see the page open in your web browser:

The page has some helpful links:

Link	Links to:
	This documentation.
(the version of this documentation)	A page listing all the different versions of this documentation. NOTE: Useful documentation starts at version 0.2.18.
	The cljdoc home page. Cljdoc is a central hub that hosts documentation for many Clojure libraries and tools (including clj-poly!).
	The polylith GitHub repo.
	Documentation for the current release.
	Documentation for the current SNAPSHOT release.
	The #polylith channel on Clojurians Slack.

Note	We automatically build a SNAPSHOT release and its associated documentation for every commit to the master branch; see releases for more details. When you use a SNAPSHOT release via a GitHub dependency, you’ll be referring to its associated SNAPSHOT documentation.

Use the search box or the left menu to navigate to pages and explore API docs:

And if you scroll down to the bottom of the left menu:

Return to the poly shell to explore, then open other available docs at any time.

From the poly shell, type doc followed by a space to see the different help categories:

example$ doc
help   more   page   ws

Doc categories:

• page - web pages constitute the poly tool user manual, which you are reading a page of right now!

• help - poly commands docs

• ws - workspace structure docs

• more - various other information: conceptual docs, blog posts, videos, podcasts, example workspaces, and other links

Let’s dig into these categories.

page

Use the page argument to open a specific poly tool documentation page in your web browser. Notice that the shell lists all pages:

example$ doc page:
artifacts                flags                    readme
base                     git-hooks                shell
build                    git                      source-code
colors                   install                  state
component                interface                tagging
configuration            introduction             tap
contact                  libraries                test-runners
continuous-integration   license                  testing
dependencies             naming                   tools-deps
developing-poly          polylith-ci-setup        upgrade
development              polyx                    validations
doc                      production-systems       versions
example-systems          profile                  workspace
explore-the-workspace    project

These are the same pages you see listed in the left menu in your web browser.

When you select a page, poly will open it in your web browser. To open the flags page:

doc page:flags

help

The help argument takes you to the poly commands documentation:

example$ doc help

Ask the shell to list all command help with:

example$ doc help:
check                deps-project         shell
create-base          deps-workspace       switch-ws
create-component     deps                 tap
create-project       diff                 test
create-workspace     doc                  version
create               info                 ws
deps-brick           libs
deps-project-brick   overview

To open the check command:

example$ doc help:check

The poly tool will open help for the check command in your web browser.

Tip	You can get the same help at your terminal via: example$ help check

ws

The ws argument takes you to the Workspace structure documentation:

example$ doc ws

List all top keys via:

example$ doc ws:
bases          name           user-input
changes        old            version
components     paths          ws-dir
configs        profiles       ws-local-dir
interfaces     projects       ws-reader
messages       settings       ws-type

Open the description for a specific top key in your web browser:

example$ doc ws:configs

more

The more argument covers all other documentation and links that are not specifically about the poly tool:

example$ doc more:
blog-posts    python-tool
high-level    slack
in-japanese   videos
podcasts      workspaces

Let’s dig into the different categories:

blog posts

Open blog posts via:

example$ doc more:blog-posts:
a-fresh-take-on-monorepos-in-python
how-polylith-came-to-life
leveraging-polylith-to-improve-consistency-reduce-complexity-and-increase-changeability
the-micro-monolith-architecture
the-monorepos-polylith-series
the-origin-of-complexity
understanding-polylith-through-the-lens-of-hexagonal-architecture

Blog post	What	Published
leveraging-polylith-to-improve-consistency-reduce-complexity-and-increase-changeability	Felix Barbalet explains how Poilylith helps reduce complexity in an existing production system.	2024
understanding-polylith-through-the-lens-of-hexagonal-architecture	Joakim Tengstrand explains the differences between the Hexagonal architecture and Polylith.	2023
a-fresh-take-on-monorepos-in-python	David Vujic explains what would happen if they had Polylith in the Python community.	2022
the-monorepos-polylith-series	Sean Corfield describes his experience migrating a big production system to Polylith in a series of blog posts.	2021-2023
the-origin-of-complexity	Joakim Tengstrand explains the foundational concepts that Polylith is built upon.	2019
how-polylith-came-to-life	Joakim Tengstrand explains how the Polylith architecture came to life.	2018
the-micro-monolith-architecture	Joakim Tengstrand explains the ideas behind Micro Monolith, a predecessor to Polylith.	2016

high-level

Open conceptual, high-level documentation:

example$ doc more:high-level

You can list all pages in the left menu with:

example$ doc more:high-level:
advantages-of-polylith
base
bring-it-all-together
component
current-architectures
development-project
faq
polylith-in-a-nutshell
production-systems
project
sharing-code
simplicity
testing-incrementally
tool
transitioning-to-polylith
videos
who-made-this
why-the-name-polylith
workspace

Open a specific page, for example, the FAQ page, via:

example$ doc more:high-level:faq

in japanese

Shinsei Taro (しんせいたろう) has translated and reworked version 0.2.19 of the poly tool in Japanese, here.

podcasts

You can open the first episode of the only podcast we have with:

example$ doc more:podcasts:polylith-with-joakim-james-and-furkan:part1

Podcast	What	Published
polylith-with-joakim-james-and-furkan:part1	Jacek Schae discusses the Polylith architecture with the Polylith team where they explain the ideas behind Polylith.	2021
polylith-with-joakim-james-and-furkan:part2	The same people go deeper into the Polylith concepts, its benefits, and how it differs from other ways of working with code.	2021

python tool

David Vujic has created Polylith tools for Python:

example$ doc more:python-tool

slack

Reach out to the Polylith team in the #polylith channel in the Clojurians Slack:

example$ doc more:slack

videos

You can list available videos with:

example$ doc more:videos:
a-fresh-take-on-monorepos-in-python
collaborative-learning-polylith
how-the-polylith-repo-has-evolved-over-time
polylith-in-a-nutshell
polylith–a-software-architecture-based-on-lego-like-blocks
the-last-architecture-you-will-ever-need

Video	What	Published
how-the-polylith-repo-has-evolved-over-time	An animation that visualizes the evolution of the Polylith repository from its inception in 2020 to mid-2024. Generated in Gource.	2024
a-fresh-take-on-monorepos-in-python	David Vujic explains how Polylith can be used in Python.	2023
collaborative-learning-polylith	Sean Corfield is interviewed by the Los Angeles Clojure Users Group about his experience with Polylith and how he uses the poly tool in production at World Singles Network.	2022
the-last-architecture-you-will-ever-need	Joakim Tengstrand and Furkan Bayraktar try to convince people why Polylith is the last architecture they will ever need!	2020
polylith-in-a-nutshell	James Trunk explains the basic concepts of the Polylith architecture.	2019
polylith–a-software-architecture-based-on-lego-like-blocks	Joakim Tengstrand explains how Polylith is like building with LEGO bricks, at ClojureD 2019.	2019

workspaces

List example poly workspace with:

example$ doc more:workspaces:
game-of-life
polylith
realworld
usermanager

Workspace	What
game-of-life	A tiny workspace that implements Game of Life, created by Joakim Tengstrand.
polylith	The Polylith workspace, from which this poly tool itself is built, mainly maintained by Joakim Tengstrand.
realworld	A full-fledged RealWorld server, built with Clojure, Polylith, and Ring, including CRUD operations, authentication, routing, pagination, and more. Created and maintained by Furkan Bayraktar.
usermanager	A simple web application using Component, Ring, Compojure, and Selmer connected to a local SQLite database. Created and maintained by Sean Corfield.