utopia-project 0.34.1 → 0.35.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6d7813076feeeb716ee8b2fed2db46d2d5522d63ef443632687aec95be009f9
-  data.tar.gz: a77ff26f76a698e3d9c90b86270a4ee9fefeecd6108e9bade9c5d603ffe38081
+  metadata.gz: cfd904d0661eca52af7af1d7c16cc1e39fc9664dcc6d1b263693a779d7777a06
+  data.tar.gz: f0ab7c6d9c241794d58de46dfaa6db3d0dd44888aebeac0211dcf8e96b7b15c0
 SHA512:
-  metadata.gz: 33e47b9495910bd0e04b7b3f35f05f06de0e02c827dcb2c08cc8619b81b70e9986b288f4014a3c5fa544b38c97a21e3373287f49881ad67cedd868353b4e91cf
-  data.tar.gz: aad59c90eb1f6556f6332f42afab40bc81031f2414df7fe83231a9bdb71fe2de7f6a4491aec52b53ab225049732c3d7cd0f92722ae4813331bebc29385c2be3c
+  metadata.gz: 22229199613c3b999385d16b9ba274e6453929a36b86e832f4699f096dceeeec6b0e6d9201e0a5e2c870fed38ea6f44c76cba5b84c21a7ac16dd0f9b8ce7e186
+  data.tar.gz: a46c96093621d0e759dffd4ee838aaffdb7ba1beb6477ced3fdc00b358fc094f6aa5cd235ee27741147c789bf2b0f2eeec7c4d424477549e11488bd87bffd3be

data/context/documentation-guidelines.md

@@ -0,0 +1,105 @@
+# Documentation Guides
+
+This guide explains how to create and maintain documentation for your project using `utopia-project`.
+
+## Overview
+
+There are two main aspects to consider when creating documentation with `utopia-project`:
+
+1. **Source Code Documentation**: This involves adding documentation directly within your code using special tags.
+2. **Examples & Guides**: This includes creating separate example files and guides to help users understand how to use your project.
+
+### Source Code Documentation
+
+Source code documentation is included adjacent to the code it describes, using special tags to provide structured information. This allows for easy generation of documentation from the source code itself. The `utopia-project` documentation generator uses the `decode` gem (which is documented elsewhere).
+
+However, in short:
+
+- Documentation is expected to be in markdown format.
+- You may embed links to definitions using `{MyClass}` or `{my_method}`.
+- You can use tags:
+  - `@parameters name [Type] Description.`
+  - `@yields {|argument| ...} If a block is given.`
+  - `@returns [Type] Description.`
+- Classes and Modules should typically be described as "Represents a ..." where it makes sense to do so.
+
+In addition, for complex classes that require extra documentation, e.g. `my_class.rb` can have an adjacent `my_class.md` which should have the title `# MyClass` and can include additional details, examples, and usage guidelines.
+
+### Examples & Guides
+
+In addition to source code documentation, it's helpful to provide separate examples and guides to demonstrate how to use your project. This can include:
+
+- Code snippets that illustrate common use cases.
+- Step-by-step tutorials for more complex scenarios.
+
+By providing both inline documentation and separate guides, you can help users understand your project more easily and encourage adoption.
+
+These resources are located in the `guides/` directory of your project, and have the following format:
+
+```
+guides/
+├── links.yaml
+├── documentation-guidelines/
+│   └── readme.md
+├── documentation-guides/
+│   └── readme.md
+├── getting-started/
+│   └── readme.md
+└── github-pages-integration/
+    └── readme.md
+```
+
+The `links.yaml` file comes from the `utopia` framework, and is used to define metadata and ordering of the guides, e.g.
+
+```yaml
+# guides/links.yaml
+getting-started:
+  order: 1
+github-pages-integration:
+  order: 2
+documentation-guides:
+  order: 3
+```
+
+Every guide should start with a brief overview, explaining its purpose and what the user can expect to learn: "This guide explains how to use x to do y." – it should be short and to the point, as it's used as the description of the guide on other pages that link to it.
+
+#### "Getting Started" Guide
+
+Every project should have a "Getting Started" guide that provides an introduction to the project, including the following sections:
+
+~~~markdown
+# Getting Started
+
+This guide explains how to get started with `$project`.
+
+## Installation
+
+Add the gem to your project:
+
+```bash
+$ bundle add $project
+```
+
+## Core Concepts
+
+`$project` has several core concepts:
+
+- A {ruby MyProject::MyClass} which represents the main entry point for using the project.
+
+## Usage
+
+Brief explaination about usage.
+
+### Specific Scenario
+
+More detailed explanation about usage in a specific scenario.
+
+```ruby
+# some example code
+```
+~~~
+
+In the above example:
+
+- "Core Concepts" is optional and should be included if it helps to clarify the usage and structure of the project.
+- "Specific Scenario" only makes sense if there are more than one scenario that is typical.

data/context/getting-started.md

@@ -1,15 +1,17 @@
 # Getting Started
 
-This guide explains how to use `utopia-project` for your own project.
+This guide explains how to use `utopia-project` to add documentation to your project.
 
 ## Installation
 
-Firstly, add the gem to your project:
+Add the gem to your project:
 
 ~~~ bash
 $ bundle add utopia-project
 ~~~
 
+## Usage
+
 ## Start Local Server
 
 Start the local server to preview documentation:

data/context/github-pages-integration.md

@@ -1,17 +1,67 @@
 # GitHub Pages Integration
 
-This guide shows you how to use `utopia-project` with GitHub Pages.
+This guide shows you how to use `utopia-project` with GitHub Pages to deploy documentation.
 
-## Static Site Generation
+## Enable GitHub Pages
 
-Once you are happy with your project's documentation, use this command to generate a static site:
+In your GitHub project settings, you will need to [enable GitHub Pages from a custom GitHub Actions workflow](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow). Then, use the workflow below to publish the documentation:
 
-~~~ bash
-$ bake utopia:project:static
-~~~
+```yaml
+name: Documentation
 
-This will generate a static copy of your documentation into `docs/` which is what is required by GitHub Pages.
+on:
+  push:
+    branches:
+      - main
 
-## Enable GitHub Pages
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment:
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+env:
+  BUNDLE_WITH: maintenance
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
 
-In your GitHub project settings, you will need to [enable GitHub Pages served from `docs/`](https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#choosing-a-publishing-source).
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ruby
+        bundler-cache: true
+    
+    - name: Installing packages
+      run: sudo apt-get install wget
+    
+    - name: Generate documentation
+      timeout-minutes: 5
+      run: bundle exec bake utopia:project:static --force no
+    
+    - name: Upload documentation artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: docs
+  
+  deploy:
+    runs-on: ubuntu-latest
+    
+    environment:
+      name: github-pages
+      url: ${{steps.deployment.outputs.page_url}}
+    
+    needs: generate
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+```

data/context/index.yaml

@@ -9,11 +9,13 @@ metadata:
 files:
 - path: getting-started.md
   title: Getting Started
-  description: This guide explains how to use `utopia-project` for your own project.
-- path: documentation-formatting.md
-  title: Documentation Formatting
-  description: This guide explains the conventions used by `utopia-project` when generating
-    documentation for your project.
+  description: This guide explains how to use `utopia-project` to add documentation
+    to your project.
+- path: documentation-guidelines.md
+  title: Documentation Guides
+  description: This guide explains how to create and maintain documentation for your
+    project using `utopia-project`.
 - path: github-pages-integration.md
   title: GitHub Pages Integration
-  description: This guide shows you how to use `utopia-project` with GitHub Pages.
+  description: This guide shows you how to use `utopia-project` with GitHub Pages
+    to deploy documentation.

data/lib/utopia/project/version.rb

@@ -5,6 +5,6 @@
 
 module Utopia
 	module Project
-		VERSION = "0.34.1"
+		VERSION = "0.35.1"
 	end
 end

data/readme.md

@@ -21,11 +21,11 @@ needs of my users.
 
 Please see the [project documentation](https://socketry.github.io/utopia-project/) for more details.
 
-  - [Getting Started](https://socketry.github.io/utopia-project/guides/getting-started/index) - This guide explains how to use `utopia-project` for your own project.
+  - [Getting Started](https://socketry.github.io/utopia-project/guides/getting-started/index) - This guide explains how to use `utopia-project` to add documentation to your project.
 
-  - [Documentation Formatting](https://socketry.github.io/utopia-project/guides/documentation-formatting/index) - This guide explains the conventions used by `utopia-project` when generating documentation for your project.
+  - [Documentation Guides](https://socketry.github.io/utopia-project/guides/documentation-guidelines/index) - This guide explains how to create and maintain documentation for your project using `utopia-project`.
 
-  - [GitHub Pages Integration](https://socketry.github.io/utopia-project/guides/github-pages-integration/index) - This guide shows you how to use `utopia-project` with GitHub Pages.
+  - [GitHub Pages Integration](https://socketry.github.io/utopia-project/guides/github-pages-integration/index) - This guide shows you how to use `utopia-project` with GitHub Pages to deploy documentation.
 
 ## Releases
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: utopia-project
 version: !ruby/object:Gem::Version
-  version: 0.34.1
+  version: 0.35.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -132,7 +132,7 @@ files:
 - bake/utopia/project.rb
 - bake/utopia/project/agent/context.rb
 - bake/utopia/project/readme/update.rb
-- context/documentation-formatting.md
+- context/documentation-guidelines.md
 - context/getting-started.md
 - context/github-pages-integration.md
 - context/index.yaml

data/context/documentation-formatting.md

@@ -1,67 +0,0 @@
-# Documentation Formatting
-
-This guide explains the conventions used by `utopia-project` when generating documentation for your project.
-
-## Source Code Documentation
-
-Source code documentation is expected to be in markdown format. This is different from the canonical `RDoc` format used by Ruby. However, using markdown is a good format for standardised documentation across a range of different languages.
-
-### Tags
-
-#### `@parameter`
-
-The `@parameter` tag is used to describe the parameters of a method:
-
-~~~ ruby
-# @parameter x [Integer] The x co-ordinate.
-# @parameter y [Integer] The y co-ordinate.
-def move(x, y)
-	# ...
-end
-~~~
-
-#### `@returns`
-
-The `@returns` tag is used to describe the return type of the definition:
-
-~~~ ruby
-# @returns [Integer] The result of the computation.
-def fib(n)
-	# ...
-end
-~~~
-
-### References
-
-It is possible to insert references in your documentation using curly brackets. In the following example `{Input}` will be expanded relative to the usage, to some symbol named `Input`.
-
-~~~ ruby
-# Frobulates the input, see {Input} for more details.
-def frobulate(input)
-	# ... left to the imagination ...
-end
-~~~
-
-## Examples & Guides
-
-Examples provide structured information to help users understand your project and are located in the `examples/` directory. One sub-directory per example.
-
-### `readme.md`
-
-If an example has a `readme.md` file, it is used as the main source of documentation.
-
-### Source Files
-
-All other source files are listed on the example page. Top level comments with trailing code (segments) are used to help guide the user through the example.
-
-## Diagrams
-
-You can add diagrams formatted using `mermaid.js`.
-
-``` mermaid
-	graph LR;
-			A-->B;
-			A-->C;
-			B-->D;
-			C-->D;
-```