utopia-project 0.33.2 → 0.34.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- checksums.yaml.gz.sig +0 -0
- data/bake/utopia/project/agent/context.rb +53 -0
- data/bake/utopia/project/readme/update.rb +6 -3
- data/bake/utopia/project.rb +1 -1
- data/context/documentation-formatting.md +67 -0
- data/context/getting-started.md +31 -0
- data/context/github-pages-integration.md +17 -0
- data/context/index.yaml +16 -0
- data/lib/utopia/project/base.rb +1 -1
- data/lib/utopia/project/guide.rb +11 -2
- data/lib/utopia/project/linkify.rb +1 -1
- data/lib/utopia/project/releases_document.rb +1 -1
- data/lib/utopia/project/renderer.rb +1 -1
- data/lib/utopia/project/version.rb +1 -1
- data/lib/utopia/project.rb +1 -1
- data/pages/controller.rb +1 -1
- data/pages/guides/controller.rb +1 -1
- data/pages/releases/controller.rb +1 -1
- data/pages/source/controller.rb +1 -1
- data/readme.md +4 -0
- data/releases.md +4 -0
- data/template/gems.rb +3 -0
- data/template/preload.rb +1 -1
- data.tar.gz.sig +0 -0
- metadata +7 -2
- metadata.gz.sig +0 -0
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 8e9f2b003ff67529bbe43f3597901c567860a9aee869d108e140f142a948ec6c
|
|
4
|
+
data.tar.gz: b0103f4c18319d9d48b4d7889a6bc921dc6fa0ce3c48de8b2f44bc545bbc2b75
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 98a0b74ebcdadafc34b6cecca41b456a91d63d710db9b1cef039c825f806c408abc79182dc359cfdb28a55ca4d5afeabae2cab12708d2946f44347b4ce8f9f1d
|
|
7
|
+
data.tar.gz: e95d1f143923f738312910efc6849a488cb7c8a20bae952d770d8b6bc704822af4b7b9b2c7c8e934213a5914e58f9655ea3147591fdb790558209d67753eece9
|
checksums.yaml.gz.sig
CHANGED
|
Binary file
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
# Released under the MIT License.
|
|
4
|
+
# Copyright, 2025, by Samuel Williams.
|
|
5
|
+
|
|
6
|
+
def initialize(...)
|
|
7
|
+
super
|
|
8
|
+
|
|
9
|
+
require "utopia/project"
|
|
10
|
+
end
|
|
11
|
+
|
|
12
|
+
# Update agent context files from the guides.
|
|
13
|
+
def update
|
|
14
|
+
project = Utopia::Project::Base.new(context.root)
|
|
15
|
+
|
|
16
|
+
FileUtils.mkdir_p self.context_root
|
|
17
|
+
index = {}
|
|
18
|
+
|
|
19
|
+
project.guides.each do |guide|
|
|
20
|
+
if guide.readme?
|
|
21
|
+
FileUtils.cp guide.readme_path, self.context_path_for(guide)
|
|
22
|
+
index[guide.name] = {
|
|
23
|
+
"title" => guide.title,
|
|
24
|
+
"order" => guide.order,
|
|
25
|
+
"description" => guide.description.to_markdown.chomp,
|
|
26
|
+
}
|
|
27
|
+
end
|
|
28
|
+
end
|
|
29
|
+
|
|
30
|
+
if index.any?
|
|
31
|
+
File.open(self.context_index_path, "w") do |file|
|
|
32
|
+
file.puts "# Automatically generated context index for Utopia::Project guides."
|
|
33
|
+
file.puts "# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`."
|
|
34
|
+
YAML.dump(index, file)
|
|
35
|
+
end
|
|
36
|
+
end
|
|
37
|
+
|
|
38
|
+
return index
|
|
39
|
+
end
|
|
40
|
+
|
|
41
|
+
private
|
|
42
|
+
|
|
43
|
+
def context_root
|
|
44
|
+
File.join(context.root, "context")
|
|
45
|
+
end
|
|
46
|
+
|
|
47
|
+
def context_path_for(guide)
|
|
48
|
+
File.join(context_root, guide.name + ".md")
|
|
49
|
+
end
|
|
50
|
+
|
|
51
|
+
def context_index_path
|
|
52
|
+
File.join(context_root, "index.yaml")
|
|
53
|
+
end
|
|
@@ -3,8 +3,11 @@
|
|
|
3
3
|
# Released under the MIT License.
|
|
4
4
|
# Copyright, 2023-2025, by Samuel Williams.
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
|
|
6
|
+
def initialize(...)
|
|
7
|
+
super
|
|
8
|
+
|
|
9
|
+
require "utopia/project"
|
|
10
|
+
end
|
|
8
11
|
|
|
9
12
|
def update(path: "readme.md", documentation_url: nil)
|
|
10
13
|
project = Utopia::Project::Base.new(context.root)
|
|
@@ -83,7 +86,7 @@ def releases_section(documentation_url, project)
|
|
|
83
86
|
buffer = String.new
|
|
84
87
|
|
|
85
88
|
buffer << "Please see the [project releases](#{documentation_url}releases/index) for all releases.\n"
|
|
86
|
-
|
|
89
|
+
|
|
87
90
|
project.releases.first(10).each do |release|
|
|
88
91
|
buffer << "\n### #{release.name}\n\n"
|
|
89
92
|
|
data/bake/utopia/project.rb
CHANGED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# Documentation Formatting
|
|
2
|
+
|
|
3
|
+
This guide explains the conventions used by `utopia-project` when generating documentation for your project.
|
|
4
|
+
|
|
5
|
+
## Source Code Documentation
|
|
6
|
+
|
|
7
|
+
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.
|
|
8
|
+
|
|
9
|
+
### Tags
|
|
10
|
+
|
|
11
|
+
#### `@parameter`
|
|
12
|
+
|
|
13
|
+
The `@parameter` tag is used to describe the parameters of a method:
|
|
14
|
+
|
|
15
|
+
~~~ ruby
|
|
16
|
+
# @parameter x [Integer] The x co-ordinate.
|
|
17
|
+
# @parameter y [Integer] The y co-ordinate.
|
|
18
|
+
def move(x, y)
|
|
19
|
+
# ...
|
|
20
|
+
end
|
|
21
|
+
~~~
|
|
22
|
+
|
|
23
|
+
#### `@returns`
|
|
24
|
+
|
|
25
|
+
The `@returns` tag is used to describe the return type of the definition:
|
|
26
|
+
|
|
27
|
+
~~~ ruby
|
|
28
|
+
# @returns [Integer] The result of the computation.
|
|
29
|
+
def fib(n)
|
|
30
|
+
# ...
|
|
31
|
+
end
|
|
32
|
+
~~~
|
|
33
|
+
|
|
34
|
+
### References
|
|
35
|
+
|
|
36
|
+
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`.
|
|
37
|
+
|
|
38
|
+
~~~ ruby
|
|
39
|
+
# Frobulates the input, see {Input} for more details.
|
|
40
|
+
def frobulate(input)
|
|
41
|
+
# ... left to the imagination ...
|
|
42
|
+
end
|
|
43
|
+
~~~
|
|
44
|
+
|
|
45
|
+
## Examples & Guides
|
|
46
|
+
|
|
47
|
+
Examples provide structured information to help users understand your project and are located in the `examples/` directory. One sub-directory per example.
|
|
48
|
+
|
|
49
|
+
### `readme.md`
|
|
50
|
+
|
|
51
|
+
If an example has a `readme.md` file, it is used as the main source of documentation.
|
|
52
|
+
|
|
53
|
+
### Source Files
|
|
54
|
+
|
|
55
|
+
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.
|
|
56
|
+
|
|
57
|
+
## Diagrams
|
|
58
|
+
|
|
59
|
+
You can add diagrams formatted using `mermaid.js`.
|
|
60
|
+
|
|
61
|
+
``` mermaid
|
|
62
|
+
graph LR;
|
|
63
|
+
A-->B;
|
|
64
|
+
A-->C;
|
|
65
|
+
B-->D;
|
|
66
|
+
C-->D;
|
|
67
|
+
```
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# Getting Started
|
|
2
|
+
|
|
3
|
+
This guide explains how to use `utopia-project` for your own project.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
Firstly, add the gem to your project:
|
|
8
|
+
|
|
9
|
+
~~~ bash
|
|
10
|
+
$ bundle add utopia-project
|
|
11
|
+
~~~
|
|
12
|
+
|
|
13
|
+
## Start Local Server
|
|
14
|
+
|
|
15
|
+
Start the local server to preview documentation:
|
|
16
|
+
|
|
17
|
+
~~~ bash
|
|
18
|
+
$ bake utopia:project:serve
|
|
19
|
+
~~~
|
|
20
|
+
|
|
21
|
+
Right now, this server does not reload the code index, so you will need to restart the server to update the code index. This will be fixed in the future.
|
|
22
|
+
|
|
23
|
+
## Generate Static Site
|
|
24
|
+
|
|
25
|
+
You can generate a static copy of your documentation into the `docs/` folder:
|
|
26
|
+
|
|
27
|
+
~~~ bash
|
|
28
|
+
$ bake utopia:project:static
|
|
29
|
+
~~~
|
|
30
|
+
|
|
31
|
+
You can check the [guide for GitHub Pages](../github-pages-integration/index) which gives more details on how to deploy the static site using GitHub.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# GitHub Pages Integration
|
|
2
|
+
|
|
3
|
+
This guide shows you how to use `utopia-project` with GitHub Pages.
|
|
4
|
+
|
|
5
|
+
## Static Site Generation
|
|
6
|
+
|
|
7
|
+
Once you are happy with your project's documentation, use this command to generate a static site:
|
|
8
|
+
|
|
9
|
+
~~~ bash
|
|
10
|
+
$ bake utopia:project:static
|
|
11
|
+
~~~
|
|
12
|
+
|
|
13
|
+
This will generate a static copy of your documentation into `docs/` which is what is required by GitHub Pages.
|
|
14
|
+
|
|
15
|
+
## Enable GitHub Pages
|
|
16
|
+
|
|
17
|
+
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).
|
data/context/index.yaml
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Automatically generated context index for Utopia::Project guides.
|
|
2
|
+
# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
|
|
3
|
+
---
|
|
4
|
+
getting-started:
|
|
5
|
+
title: Getting Started
|
|
6
|
+
order: 1
|
|
7
|
+
description: This guide explains how to use `utopia-project` for your own project.
|
|
8
|
+
documentation-formatting:
|
|
9
|
+
title: Documentation Formatting
|
|
10
|
+
order: 2
|
|
11
|
+
description: This guide explains the conventions used by `utopia-project` when generating
|
|
12
|
+
documentation for your project.
|
|
13
|
+
github-pages-integration:
|
|
14
|
+
title: GitHub Pages Integration
|
|
15
|
+
order: 3
|
|
16
|
+
description: This guide shows you how to use `utopia-project` with GitHub Pages.
|
data/lib/utopia/project/base.rb
CHANGED
data/lib/utopia/project/guide.rb
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
3
|
# Released under the MIT License.
|
|
4
|
-
# Copyright, 2020-
|
|
4
|
+
# Copyright, 2020-2025, by Samuel Williams.
|
|
5
5
|
|
|
6
6
|
require "utopia/path"
|
|
7
7
|
require "xrb/reference"
|
|
@@ -14,9 +14,10 @@ module Utopia
|
|
|
14
14
|
# Initialize the example with the given root path.
|
|
15
15
|
# @parameter base [Base] The base instance for the project.
|
|
16
16
|
# @parameter root [String] The file-system path to the root of the example.
|
|
17
|
-
def initialize(base, root)
|
|
17
|
+
def initialize(base, root, metadata)
|
|
18
18
|
@base = base
|
|
19
19
|
@root = root
|
|
20
|
+
@metadata = metadata
|
|
20
21
|
|
|
21
22
|
@documentation = nil
|
|
22
23
|
|
|
@@ -31,6 +32,14 @@ module Utopia
|
|
|
31
32
|
# @attribute [String | Nil]
|
|
32
33
|
attr :description
|
|
33
34
|
|
|
35
|
+
# The metadata associated with the guide.
|
|
36
|
+
# @attribute [Hash]
|
|
37
|
+
attr :metadata
|
|
38
|
+
|
|
39
|
+
def order
|
|
40
|
+
metadata[:order]
|
|
41
|
+
end
|
|
42
|
+
|
|
34
43
|
README = "readme.md"
|
|
35
44
|
|
|
36
45
|
# The path to the README file for the guide.
|
data/lib/utopia/project.rb
CHANGED
data/pages/controller.rb
CHANGED
data/pages/guides/controller.rb
CHANGED
data/pages/source/controller.rb
CHANGED
data/readme.md
CHANGED
|
@@ -31,6 +31,10 @@ Please see the [project documentation](https://socketry.github.io/utopia-project
|
|
|
31
31
|
|
|
32
32
|
Please see the [project releases](https://socketry.github.io/utopia-project/releases/index) for all releases.
|
|
33
33
|
|
|
34
|
+
### v0.34.0
|
|
35
|
+
|
|
36
|
+
- Introduce `bake utopia:project:agent:context:update` command to update the agent context from the guides in the project.
|
|
37
|
+
|
|
34
38
|
### v0.33.2
|
|
35
39
|
|
|
36
40
|
- Fixed handling of segmented code guides when rendered into a `readme.md` file.
|
data/releases.md
CHANGED
data/template/gems.rb
CHANGED
data/template/preload.rb
CHANGED
data.tar.gz.sig
CHANGED
|
Binary file
|
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: utopia-project
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.
|
|
4
|
+
version: 0.34.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Samuel Williams
|
|
@@ -130,7 +130,12 @@ extensions: []
|
|
|
130
130
|
extra_rdoc_files: []
|
|
131
131
|
files:
|
|
132
132
|
- bake/utopia/project.rb
|
|
133
|
+
- bake/utopia/project/agent/context.rb
|
|
133
134
|
- bake/utopia/project/readme/update.rb
|
|
135
|
+
- context/documentation-formatting.md
|
|
136
|
+
- context/getting-started.md
|
|
137
|
+
- context/github-pages-integration.md
|
|
138
|
+
- context/index.yaml
|
|
134
139
|
- lib/utopia/project.rb
|
|
135
140
|
- lib/utopia/project/base.md
|
|
136
141
|
- lib/utopia/project/base.rb
|
|
@@ -278,7 +283,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
|
278
283
|
- !ruby/object:Gem::Version
|
|
279
284
|
version: '0'
|
|
280
285
|
requirements: []
|
|
281
|
-
rubygems_version: 3.6.
|
|
286
|
+
rubygems_version: 3.6.9
|
|
282
287
|
specification_version: 4
|
|
283
288
|
summary: A project documentation tool based on Utopia.
|
|
284
289
|
test_files: []
|
metadata.gz.sig
CHANGED
|
Binary file
|