Review and update Install doc #331
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Formatted overview on ways to install to a table. For me this works better to compare variations. It also helped me to fill in some missing blanks. And to remove some details unnecessary for an overview (I moved some of these details down to specific install sections). Let me know if this works for you too. Noticed that overview mentions how to switch versions but install instructions do not talk about this. Did nothing about this yet. Subtle: tried to use "we" only when talking from Polylith core team, and used "you" when talking to and guiding the reader. Assumed poly core team preference is poly as stand-alone and/or Clojure CLI dep. Can adjust advice if this is not the case. But making some clear suggestion avoids overwhelming newcomers. Noticed some prerequisite and post-install advice repeated in some install instructions. But inconsistently. I moved these to adoc custom attributes so we have less copy/paste. Now using adoc `subs="attributes+"` option in code blocks. This way code blocks can now reflect the `:poly-version:` attribute. Moved clojure cli dep install instructions before clojure tools install instructions. This matches the overview order, and it (maybe?) the more likely order of interest for readers. Added "stand-alone" to all headings that describe stand-alone installation. Just to make it extra clear. Moved logging deps config to tools deps usage section as it only applies to that usage. Re-orged Clojure Tools instructions a bit. Clarified, I think, how it processes args. Noticed that JVM options only applies to stand-alone variants to added that detail. I also noticed that it does not give an example, which I thought would be useful, but did nothing about that.
|
@tengstrand This one took some time to review. |
tengstrand
requested changes
Sep 14, 2023
|
|
||
| An alternative is to give a `sha`, which allows us to use old versions or versions that hasn't been released yet, e.g.: | ||
| An alternative way of executing the `poly` tool is to specify it as a dependency in your `./deps.edn` file. |
There was a problem hiding this comment.
Most sentences use our instead of your, or we instead of you, as if we did this together. Change this to make it consistent.
There was a problem hiding this comment.
Yes, from my (admittedly huge) commit comment:
Subtle: tried to use "we" only when talking from Polylith core team, and used "you" when talking to and guiding the reader.
My personal feeling is using "our" and "we" is a bit confusing and makes me sometimes wonder what "I" should be doing. It's subtle. I just did a web search and found this:
https://bernoff.com/blog/the-pronoun-conundrum-we-vs-you-in-business-advice
This is subjective and will adhere to your preference, lemme know.
There was a problem hiding this comment.
Hmm, interesting! This is important, so let me check this and come back to you!
|
|
||
| [#install-on-mac] | ||
| == Install on Mac | ||
| == Install as Stand-alone on macOS |
There was a problem hiding this comment.
Do we need to use upper case for Stand-alone? I prefer stand-alone, if you don't have any strong opinions.
There was a problem hiding this comment.
No strong opinion at all, but capitalization for section titles should probably be consistent, whatever convention you choose.
There was a problem hiding this comment.
Maybe it is nice to capitalize headings "Like normal sentences"? I think that is fine too, lemme know.
There was a problem hiding this comment.
Yes, capitalizing the headings, but lower case elsewhere.
There was a problem hiding this comment.
So... to make sure I got it: for headings you'd like for example:
== The Dog and Cat are Friends
Instead of
== The dog and cat are friends
(So Stand-alone would remain capitalized?)
I'm fine either way. Lemme know.
| ---- | ||
|
|
||
| We can get basic built-in help via the CLI's help machinery: | ||
| An alternative to specifying a `:git/tag` is to specify a `:git/sha`. | ||
| This allows you to install any git revision poly and is often used to test out a version that has not been officially released yet: |
There was a problem hiding this comment.
I try to use us (and we) when possible instead of you, as if we are doing this together.
There was a problem hiding this comment.
See previous comment on us and we.
|
|
||
| [source,clojure] | ||
| For this reason, it can be convenient to first launch a `poly` shell so you can use the conventional `poly` command-line argument syntax. |
|
|
||
| [source,clojure] | ||
| For this reason, it can be convenient to first launch a `poly` shell so you can use the conventional `poly` command-line argument syntax. | ||
| Let's say you want to get info on lines of code. |
| ---- | ||
|
|
||
| [#github-dependency] | ||
| Via GitHub: | ||
| After which you can specify standard Polylith arguments: |
And append colon to 1st col text.
Also got around normal heading capitalization convention by quoting master as code.
I accidentally deleted this.
|
Ok @tengstrand: I've made a pass-through and addressed your feedback. Known remaining items that I see:
|
tengstrand
approved these changes
Sep 16, 2023
There was a problem hiding this comment.
This looks really good and all changes make sense to me! I haven't check with my "English teacher friend" yet regarding the use of you/we, but I just decided to go with "your" style for now and use you as default. It's really hard to decide when to use we or you, so having you as default kind of makes sense because it's "never wrong" which we sometimes is. You can use we whenever that feels convenient, but let's figure this out later!
tengstrand
added a commit
that referenced
this pull request
Oct 1, 2023
* Added Continuous Integration with two sub pages in the left menu.
* Changed the :toc: depth to 4 for the CI Deployment page.
* Changed back CI pages.
* Added section for how to start a shell in another workspace + Rarely used parameters, in shell.adoc.
Suggest :all in the help autocomplete if passing in :all when starting a shell.
* Updated "parameters used when maintaining the poly tool".
* An early version of the 'doc' command.
* Fixed failing tests.
* Documented the release versioning strategy in the version component.
* Updated formatting in build.clj.
* Make sure we only create a jar and deploys github for the poly project.
* First working version of the doc command with support for browsing pages.
* Support for "doc page:ws-structure:KEY".
* Pass command, page, or ws to the doc command as first argument.
* Refactored the doc command.
* Refer to the nicer links in the workspace structure. Don't include pages under Reference in the "doc page:PAGE" command.
* Moved ci-deployment.adoc to continuous-integration.adoc.
* Moved up the :toc: in ci doc.
* Updated the CI page.
* Created the doc component and cleaned up the code.
* Added more pages under the more key, to the doc command.
* Added more pages under the more key, to the doc command.
* Updated the doc command pages.
* Added a few ^:no-doc.
* Added the internal documentation for the doc command.
* Added doc related keys to the user-input section of workspace-structure.adoc.
* Moved back the polylith ci documentation into its own page.
* Cleaned up the way we configure the doc page navigation.
* Added autocomplete tests for the doc command. Bumped portal to 0.45.1.
* Added a note for the "root module" problem that is reported in issue 2828 in Cursive.
* Added "The poly tool documentation" to the readme page.
* Set version.revision to "" temporarily.
* Updated the readme.
* Updated the readme (testing).
* Updated the readme.
* Updated link to the introduction.
* Added the nav-generator + generate navigation data used by the doc command in the shell component.
* Refactored print-logo.
* Changed from 'doc command' to 'doc help'.
* Renamed command help files in output + moved script files to scripts/help.
* Updated :user-input > :command in workspace-structure.adoc.
* Allow the doc command to be executed outside a workspace.
* Experiment with variables in the introduction.adoc page.
* Import code examples in the doc, to remove duplication and reduce maintenance cost.
* Reverted the addition of includes.
* Added missing statement i create script.
* Minor fixes to the create script + added test of {site.base_url} attribute on the introduction.adoc page.
* Try to change the link to the api on the test-runner page.
* Try to change the link to the api on the test-runner page, to xref.
* Removed alt= from image tags.
* Test env-cljdoc attribute on the introduction page.
* Tried links in the introduction page.
* Updated help texts.
* Open document in github if executing "doc page:PAGE branch:BRANCH".
* Make sure we go to the correct page in the doc command, even when we only pass in 'help' or 'ws'.
* Moved the more doc configuration to its own file.
* Added doc.adoc.
* Added doc to the left menu.
* Updated the doc page.
* Updated the documentation.
* Changed to use code blocks instead of cursive text for code and paths.
* Updated the documentation.
* Fixed the problem with the flags page + added autowidth to tables.
* Put "a > b > c" blocks in single backtick pairs.
* Prepare for SHAPSHOT releases of clj-poly jar to Clojars, which will trigger a cljdoc build. If asking the tool for the latest sha, take it from current branch if is in the polylith repo.
* Add a couple of badges.
* Removed "# snapshot" from version.
* Calculate latest commited sha directly via polylith in build.clj.
* Updated version date and comment.
* Remove backticks in the status column of the flgs tables.
* Support starting a shell with "poly :local".
* Added version to the list of commands. Improved the explanation of how releases are done.
* Added help text for the version command.
* Updated the help.
* Make sure all help texts fit in the cljdoc commands section.
* Make sure all help texts fit in the cljdoc commands section (updated the output).
* Bumped tools.build to 0.9.5.
* Fix filename/namespace mismatch in profile.adoc (#324)
Fixes user-remote code snippets with filenames not matching their declared namespaces
* Added releases component
* Fixed failing tests.
* Added more info about :releases in the workspace structure.
* Updated the doc page.
* Changed the formatting for the test runner authors.
* Updated the polyx doc + excluded the release component from the API.
* Support starting the shell in different ways + replaced the Parameters page with Maintain poly.
* Renamed to maintenance.adooc.
* Updated maintenance.adoc.
* Moved back versioning history to the version component. Removed the releases component. Created the snapshot-releases.txt document.
* Also include issue 205 in the text file.
* Updated + renamed.
* Updated.
* Updated next-shapshot-release.txt.
* Updated configuration.adoc + next-shapshot-release.txt.
* Added poly-as-a-library.adoc. Added version:api to the workspace structure. Updated the API doc in the api component.
* Updated comment in api.
* Updated docstring in api.
* Updated docstring in api (new try).
* Updated poly-as-a-library.adoc.
* Fixed failing tests.
* Changed how we store versions in the API. Removed version.ws.ws-type and version.from.ws.type.
* Removed comment from api-version.
* Added artifacts.adoc.
* Open the github readme.adoc when executing the doc command within a shell that has been started with :local. Corrected the English in next-release.txt.
* Added blank row between image and text "When this turns up".
* Second try, with {nbsp}.
* Replace "0.2.18" with {poly-version} in these files: install.adoc, poly-as-a-library.adoc, shell.adoc, upgrade.adoc, workspace-structure.adoc.
* Updated text that is shown when creating a brick. Use {cljdoc-doc-url}in the introduction link in readme.adoc.
* Updated doc for api-version. Changed link to the poly tool documentation, that is created by the 'create workspace' command.
* Changed to a generic link for to the poly tool documentation, in the 'create workspace' command.
* Added Hyunwoo Nam as a Polylith Friend sponsor. Thanks!
* Fixed layout of the Polylith Friends.
* Try to Fix layout of the Polylith Friends.
* Try to Fix layout of the Polylith Friends.
* Try to Fix layout of the Polylith Friends.
* Try to Fix layout of the Polylith Friends.
* bb doc: improve docker dameon error msg (#325)
If the docker daemon is not running we now present a much more concise
error message (the cause was previously shown but obscured by a big
stack trace).
* Updated comments in interface on how to update versioning.
* Configured data readers for edamame. Changed key names for old poly versions in ./deps.edn. Updated next-release.txt.
* Added overview.png.
* Renamed to poly-maintenance.adoc + updated.
* Support starting a shell as e.g. 'poly ws-dir:examples/doc-example' or with ws-file.
* Try to improve formatting in the api doc.
* Updated release description in 'version'.
* Updated poly-as-a-library.adoc.
* Bumped the djblue/portal library.
* Minor updates of poly-as-a-library.adoc.
* Updated source-code.adoc.
* Updated artifacts.adoc.
* Various changes to the doc.
* Updated poly-as-a-library.adoc.
* Improve the api doc.
* Changed from :type in :configs > :ENTITIES > PROJECT from keyword to string.
* Updated api doc.
* Store the workspace in :configs > :workspaces > WORKSPACE, instead of in :configs > workspace
* Refactored read-brick-config-files.
* Change keys from :config to :deps in :configs for bricks and projects.
* Moved some of the documentation from poly-as-a-library to the API documentation.
* Moved the poly-as-a-library documentation to the API documentation.
* Updated configuration and the API.
* Updated the api.
* Removed the cljdoc badge (will add it again when we can link to CURRENT/SNAPSHOT).
* Removed todo.
* Replaced doc/images/poly-readme.png with doc-overview.png.
* Changed image in doc from png to svg.
* Updated doc-overview.png.
* Use doc-overview.png.
* Removed doc-overview.svg.
* Updated the doc.
* Updated the introduction of the doc section.
* Changed colors of text so that they work better in dark mode.
* Minor updates of the doc.
* Went through all the documentation and compared it with the old gitbook doc.
* Update doc-overview.png.
* Update doc-overview.png.
* Added badges for cljdoc documentation (0.2.17-alpha + 0.2.18-SNAPSHOT).
* Added badge for the 0.2.17-alpha gitbook documentation.
* Updated doc-overview.png.
* Wen through all the documentation and updated things.
* Updated the doc page.
* Removed readme.md.
* Only show the 0.2.18-SNAPSHOT link if viewing the doc in cljdoc (not in GitHub).
* Removed :is-main. Rearranged the left menu a bit. Started to work on the releases page.
* Updated release-timeline.png.
* Updated the images on the doc page.
* Updated the doc page.
* Updated the doc page.
* Updated doc images + doc.
* Created the CI section in the left menu + moved in the two CI pages + a release section.
* Updated polylith-ci-setup.adoc.
* Increased size of image.
* Updated polylith-ci-setup.adoc.
* Make sure we can navigate to the CI pages with the doc command.
* Changed link to internal clj-poly page.
* Handle CI pages when openened by the doc command correctly.
* Updated polylith-ci-setup.adoc.
* Added a note that we should not add dependencies to components from bricks.
* Reorganised the doc page a bit.
* Updated the doc page.
* Updated the doc page.
* Detect the branch when starting a shell with 'poly :github'.
* Added contact.adoc and license.adoc.
* Updated the start page in doc.
* Moved badges into the doc directory.
* Added not in the developing-poly.adoc.
* Added the cljdoc Download badge.
* Change badge links from gitbook and cljdoc to only doc.
* Changed color of the Download badge.
* Updated doc download link.
* Added the doc-download badge.
* Ignore bricks and projects that don't have a deps.edn file.
* Clarified a thing in the doc.
* Updated version date.
* Clean changes if passing in :no-changes when reading a workspace from file.
* Added the production-systems page.
* Added company workspace images.
* Minor updates of the text.
* Added images to the example systems + made them + production systems images clickable.
* Rearranged example-systems.adoc.
* Minor change.
* Removed the download badge.
* Removed the download badge (updated images).
* Went through all the documentation again.
* Updated version date.
* Moved Polylith to production-systems.adoc.
* Rename conflicting bb doc task (#328)
Babashka already has a built-in `doc` command.
To avoid conflicting, rename our `doc` task to `doc-preview`.
* First pass at adoc one sentence per line (#329)
As discussed on Slack.
See: https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line
* Review and update README (#327)
Review and update README
* Updated start page screenshot image, used in doc.adoc.
* Moved one section down a bit.
* uses instead of used.
* Added a .
* Updated the funnel workspace overview image.
* Updated link from doc to doc-preview.
* Added "as fallback".
* Updated the version section in the workspace structure.
* Added the polym alias in deps.edn for convenience.
* Bug fix for the 'libs :outdated' command.
* Bumped library versions for malli and slf4j-nop.
* Updated release-timeline.png.
* Updated the release timeline doc.
* Updated the release timeline doc with pre-release line.
* Added an example of how clj-poly is used by polylith's build.clj.
* Add kondo config exports (#332)
These come from deps and are automatically downloaded by clj-kondo
to improve linting.
Ask discussed on slack: commit them.
* Review and update Introduction (#330)
Review feedback: revert entirely to original text, but left cljdoc tip.
* Review and update Install doc (#331)
* Review and update Install doc
Formatted overview on ways to install to a table.
For me this works better to compare variations.
It also helped me to fill in some missing blanks.
And to remove some details unnecessary for an overview (I moved some of
these details down to specific install sections).
Let me know if this works for you too.
Noticed that overview mentions how to switch versions but install
instructions do not talk about this. Did nothing about this yet.
Subtle: tried to use "we" only when talking from Polylith core team, and
used "you" when talking to and guiding the reader.
Assumed poly core team preference is poly as stand-alone and/or Clojure CLI dep.
Can adjust advice if this is not the case.
But making some clear suggestion avoids overwhelming newcomers.
Noticed some prerequisite and post-install advice repeated in some
install instructions. But inconsistently. I moved these to adoc custom
attributes so we have less copy/paste.
Now using adoc `subs="attributes+"` option in code blocks.
This way code blocks can now reflect the `:poly-version:` attribute.
Moved clojure cli dep install instructions before clojure tools
install instructions. This matches the overview order, and it (maybe?)
the more likely order of interest for readers.
Added "stand-alone" to all headings that describe stand-alone
installation. Just to make it extra clear.
Moved logging deps config to tools deps usage section as it only
applies to that usage.
Re-orged Clojure Tools instructions a bit.
Clarified, I think, how it processes args.
Noticed that JVM options only applies to stand-alone variants to added
that detail. I also noticed that it does not give an example, which I
thought would be useful, but did nothing about that.
* review feedback: header style for 1st table col
And append colon to 1st col text.
* review feedback: Running from master
Also got around normal heading capitalization convention by quoting
master as code.
* review feedback: text as lang for poly shell block
* Restore link to poly release strategy
* Review and update Upgrade doc (#334)
* Review and update Upgrade doc
Done:
1. Don't immediately presume macOS.
2. Add a little generic text, from which I linked to other useful docs.
3. Match same install variations from Install doc
4. Add toc to match Install doc
5. Separate Linux and Windows (the grouping was convenient for author but not
the reader).
Not done:
1. The is no mention of SNAPSHOT builds. A reader might wonder how
to upgrade (not sure if this is even do-able for brew and nix):
1. from a final release to a SNAPSHOT release
2. from a SNAPSHOT release to a latest SNAPSHOT release under same version
* review feedback: deps.edn -> ./deps.edn
* An initial version of the deploy-snapshot function, that can deploy a snapshot to cljdoc.
* Add build scripts and CI config for SNAPSHOT builds
* Ignore clj-kondo directory except config.edn
* Auto select Polylith REPL for jack-in in Calva
* Simplified the projects-to-deploy function, so that it uses the api component instead of calling the poly tool.
* Update CI setup documentation
* Moved link.
* Added PR 327 + 332.
* Fixed link to next-release.txt.
* Review and update Production Systems doc (#337)
Reformatted text I missed in first pass to one-sentence-per-line.
Added tip on the poly reports and what they might be.
Strengthened request for companies using Polylith to make contact.
* review feedback: for tip, it is polyx not poly (#338)
* review feedback: for tip, it is polyx not poly
* Heading capitalization
* Review and update Workspace doc (#339)
* Review and update Workspace doc
Reword:
1. Change "addicted" to "enamored". I like the intent of "addicted" but I
think we can use something as powerful but more sensitive.
Clarifications:
1. mention examples assume reader is using `poly` installed as stand-alone
2. mention a git repo is, by default, created
3. mention that examples commit the created workspace
4. move `branch:` example to a tip, the reader will be less likely to
think they also need to run this variation
5. add trailing forward slash to directories. It makes it easier to see
that they are directories
6. add note that user will need to commit the generated workspace files themselves
when creating from an existing git repo
7. mention what `deps.edn` aliases are used for.
Content:
1. Update generated deps.edn `:poly` alias to use `:mvn/version`
2. Remove example and text around fetching `:latest-sha`
* Review feedback: clarify top ns usage in tip
* review feedback: base description tweak
* review feedback: state default branch is main
* review feedback: enamored -> fall in love
"Enamored" is maybe too obscure for folks whose first language is not English.
* Review and update Migrate docs (#335)
Delete the migration page.
* Review and update Example Systems doc (#336)
* Review and update Example Systems doc
Minor changes on this one.
Added a tip about the poly reports: to let the reader know what they are
and that they will learn about them soon.
* review feedback: reports are generated by polyx
* Heading capitalization
* Revise poly as a dependency workflow (#340)
The old workflow did not make sense.
* Review and update Development doc (#341)
Specific instructions are for Cursive only, make that clearer with headings.
Otherwise just edited for clarity.
Notes:
- I notice extra spacing added under images. I removed it. We can
address image/text spacing in cljdoc if we need to.
- I expect the advice Cursive specific instructions on setting up
a dev namespaces are repeated elsewhere? If not, we might want to come
back and generalize this advice for non-Cursive users.
- As of this writing the Cursive docs on tools.deps setup might be
stale, but that's not something under our domain of control.
* Updated game of life overview image.
* Review and update Interface doc (#343)
Edits for clarity.
* Review and update Component doc (#342)
Review and update Component doc
Because most IDEs now support :local/root :extra-deps, moved this
content out to its own section so it can more easily be skipped.
Don't assume all users are using Cursive.
Describe Cursive specific tip as such.
Otherwise, clarity and readability changes.
* Add developer notes on documentation (#345)
This is not a review of the Developing Poly doc, just an addition of some
notes on documentation.
* Let readers know doc improvements are a wip (#344)
Let readers know doc improvements are a work in progress.
* doc tip: add terminology for parts of command line (#347)
* Marked user as code.
* Review and update Base doc (#346)
Review and update Base doc
Distinguish cursive advice by making it a tip.
Experiment with AsciiDoc code callouts.
We'll backtrack and add them to previously reviewed docs if they seem to
add value. (I think they do).
* Prepare for SNAPSHOT release #2.
---------
Co-authored-by: Jim Riordan <jim@j1mr10rd4n.info>
Co-authored-by: Lee Read <lee@dlread.com>
Co-authored-by: Furkan Bayraktar <me@furkanbayraktar.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Formatted overview on ways to install to a table.
For me this works better to compare variations.
It also helped me to fill in some missing blanks.
And to remove some details unnecessary for an overview (I moved some of these details down to specific install sections).
Let me know if this works for you too.
Noticed that overview mentions how to switch versions but install instructions do not talk about this. Did nothing about this yet.
Subtle: tried to use "we" only when talking from Polylith core team, and used "you" when talking to and guiding the reader.
Assumed poly core team preference is poly as stand-alone and/or Clojure CLI dep. Can adjust advice if this is not the case.
But making some clear suggestion avoids overwhelming newcomers.
Noticed some prerequisite and post-install advice repeated in some install instructions. But inconsistently. I moved these to adoc custom attributes so we have less copy/paste.
Now using adoc
subs="attributes+"option in code blocks. This way code blocks can now reflect the:poly-version:attribute.Moved clojure cli dep install instructions before clojure tools install instructions. This matches the overview order, and it (maybe?) the more likely order of interest for readers.
Added "stand-alone" to all headings that describe stand-alone installation. Just to make it extra clear.
Moved logging deps config to tools deps usage section as it only applies to that usage.
Re-orged Clojure Tools instructions a bit.
Clarified, I think, how it processes args.
Noticed that JVM options only applies to stand-alone variants to added that detail. I also noticed that it does not give an example, which I thought would be useful, but did nothing about that.