Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Registry docs #189

Merged
merged 29 commits into from
Oct 11, 2024
Merged
Changes from 1 commit
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
37e6774
Registry docs stub
abstractionfactory Sep 6, 2024
2b3d282
Registry docs UI
damianstasik Sep 6, 2024
57c09c1
Move more code to build time using macros
damianstasik Sep 6, 2024
7db5681
Use existing MD pipeline and render the output to HTML at build-time
damianstasik Sep 6, 2024
47c9ba9
Clean up the code a bit
damianstasik Sep 6, 2024
8c7955b
More docs
abstractionfactory Sep 9, 2024
7d86b97
Module docs
abstractionfactory Sep 19, 2024
8abe63b
Added link to the OpenTofu docs
abstractionfactory Sep 19, 2024
cc0bdd0
Shorten sidebar
abstractionfactory Sep 19, 2024
e246034
Writing a provider
abstractionfactory Sep 26, 2024
cbebb4b
Minor fixes
abstractionfactory Sep 26, 2024
58bd6af
Warning fix
abstractionfactory Sep 26, 2024
de220fb
Minor fix
abstractionfactory Sep 26, 2024
cd9c772
Language fix
abstractionfactory Sep 26, 2024
f6f8959
Module docs
abstractionfactory Sep 26, 2024
e071bc3
Docs finished
abstractionfactory Sep 26, 2024
38846cc
Link fixes
abstractionfactory Sep 26, 2024
9baa115
Registry docs UI
damianstasik Sep 6, 2024
10aff4a
Reload docs on save in dev-mode
damianstasik Sep 26, 2024
d00aa31
Fix rebase artifact
damianstasik Sep 26, 2024
df9a583
Re-generate lock file
damianstasik Sep 26, 2024
d697cb0
Merge pull request #228 from opentofu/reload-docs-on-save-in-dev-mode
abstractionfactory Sep 26, 2024
a759ac0
Removed broken link
abstractionfactory Sep 26, 2024
30415ef
Removed broken link
abstractionfactory Sep 26, 2024
c473737
Removed broken link
abstractionfactory Sep 26, 2024
9b60c1b
Clarification in wording
abstractionfactory Sep 27, 2024
b8c6fb9
Apply suggestions from code review
abstractionfactory Oct 11, 2024
58d5891
Merge branch 'main' into registry-docs
abstractionfactory Oct 11, 2024
2a8fdbe
Fixing pnpm lock file
abstractionfactory Oct 11, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Module docs
Signed-off-by: AbstractionFactory <179820029+abstractionfactory@users.noreply.github.com>
  • Loading branch information
abstractionfactory committed Sep 26, 2024
commit 7d86b97a6c0797f14419976926bf8ee6a135886b
10 changes: 10 additions & 0 deletions frontend/docs/modules/adding.md
Original file line number Diff line number Diff line change
@@ -1 +1,11 @@
# Adding your module to the OpenTofu registry

Once you have [published your module](/docs/modules/publishing), you can add your module to the OpenTofu Registry. You can do this by [creating an issue](https://github.com/opentofu/registry/issues/new/choose) on the OpenTofu Registry GitHub repository.

Here you will have to provide your username and repository name, which will translate to a module name. For example, consider the following repository:
abstractionfactory marked this conversation as resolved.
Show resolved Hide resolved

```
YOURNAME/terraform-NAME-TARGETSYSTEM
```

This will translate to a module address your users can reference it as `YOURNAME/NAME/TARGETSYSTEM`.
abstractionfactory marked this conversation as resolved.
Show resolved Hide resolved
34 changes: 33 additions & 1 deletion frontend/docs/modules/creating.md
Original file line number Diff line number Diff line change
@@ -1 +1,33 @@
# Creating an OpenTofu module
# Creating an OpenTofu module

Any OpenTofu project can be a reusable module others can use. By pushing it to GitHub and then publishing the link to your module in the OpenTofu Registry, anyone can easily find and use it.

In order to create a module for reuse, simply write your OpenTofu code the way you normally would and create [variables](https://opentofu.org/docs/language/values/variables/) for configuration.

Your module may also create resources that a user may want to use further. For example, you may create a virtual machine and want to supply your user with the ID of that virtual machine. To return values from your module, you can use [output](https://opentofu.org/docs/language/values/outputs/) blocks.

## Readme

Once the code is done, make sure that you add a `README.md` file and explain to your users how to use your module. This file will show up in the Registry Search if the license allows for it.

## License

In order for your module to show up in the OpenTofu Registry Search, your module should be licensed under one of the [supported licenses](https://github.com/opentofu/registry-ui/blob/main/licenses.json). If your module is not under one of these licenses, your module will be findable in the Registry Search, but no other data will be displayed.

## Submodules

If you want to structure your modules further, you can use submodules you can place in subdirectories. To make the submodules show up in the Registry Search, place your submodules in the `modules/MODULENAME` directory in your module.

You can add a `README.md` file to your submodule to provide more information about your submodule.

## Examples

Similar in structure to submodules, examples provide your users with an easy way to get into using your module. To make your example show up in the OpenTofu Registry Search, place the example project into the `examples/EXAMPLENAME` folder and add a `README.md` file.

## Testing your module

Tests are a great way to ensure that your module stays working when community pull requests come in. The [`tofu test` command](https://opentofu.org/docs/cli/commands/test/) has a host of tools to let you write automated tests for your module so you can merge pull requests safely.

## Publishing your module

Once you are happy with your module, [proceed to publishing it](/docs/modules/publishing).
6 changes: 3 additions & 3 deletions frontend/docs/modules/index.md
Original file line number Diff line number Diff line change
@@ -2,6 +2,6 @@

This section shows you how to create and publish a module.

- [Creating a module](modules/creating)
- [Publishing a module](modules/publishing)
- [Adding a module to the OpenTofu Registry](modules/adding)
- [Creating a module](/docs/modules/creating)
- [Publishing a module](/docs/modules/publishing)
- [Adding a module to the OpenTofu Registry](/docs/modules/adding)
6 changes: 6 additions & 0 deletions frontend/docs/modules/publishing.md
Original file line number Diff line number Diff line change
@@ -1 +1,7 @@
# Publishing an OpenTofu module

You can host OpenTofu modules in any git repository. However, if you would like to publish the module in the OpenTofu Registry, you will need to host it on [GitHub](https://docs.github.com/en/get-started/start-your-journey).

Once you pushed your code, make sure to [create a tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) following [semantic versioning](https://semver.org/). This tag will translate to a version in the OpenTofu registry.

Once you have pushed your tag, you can now [add the module to the Registry](/docs/modules/adding).