Entropy Docs

This repository contains the documentation for the Entropy project (found in /content) and all the build scripts to create the docs.entropy.xyz site.

Project Board Issues MIT License

Table of contents

• Run locally
• Information architecture
• Repository structure
• Support
• Contributions
• License

Run locally

This repository uses the Hugo static-site-generator to build docs.entropy.xyz. To run the site locally:

1. Install Hugo. This generally boils down to either:

   # MacOS
   brew install hugo
   
   # Ubuntu
   sudo apt install hugo
   
   # Arch
   sudo pacman -S hugo

2. Clone this repository and move into the new directory:

   git clone https://github.com/entropyxyz/entropy-docs
   cd entropy-docs

3. Build and serve the site locally using Hugo:

   hugo server

4. Go to localhost:1313 in your browser.

5. To stop the local server, press CTRL + c in the terminal window.

Build the site

To build the site but not serve it, run steps 1 and 2 from the previous section, followed by hugo:

git clone https://github.com/entropyxyz/entropy-docs
cd entropy-docs
hugo

This create a new directory called public and save the site in there.

Information architecture

Documentation within this repository can be found in the /docs directory. That directory is split into the following subdirectories:

docs
|-- basics
|-- concepts
|-- guides
`-- reference

• Basics: information that everybody needs to know in order to understand, and effectivly use, Entropy.
• Concepts: discusses ideas and concepts that everyone may not be familiar with, or things that are relevant only to Entropy and not other blockchains.
• Guides: easy-to-understand guides that show users how to hit a specific goal, without diving into the content discussed in /concepts.
• Reference: in-depth reference documentation for the CLI and SDK.

Site features

This site contains quite a few shortcodes that writers can use to add extra functionality into each page.

Tooltips

Tooltips allow the reader to hover over a particular word or phrase, and have a description or explanation of that element shown to them quickly. Every avavailable tooltip can be found within ./themes/hextra/layouts/shortcodes/tooltip.html:

<!-- Create array/map of all possible tooltips. -->
{{ $tooltips := dict
  "account" "All information is associated with a specific program for a particular user or entity."
  "admin key" "A key that allows you to deploy programs and modify the settings of those programs. Admin keys cannot request signatures. This key must be funded to perform some actions."
  "adapter" "Plugins that provide support for different chains and program configurations. For example, an adapter can define a specific hashing function to use when signing. Different chains have different signing algorithms; this allows us to support them all."

...

To use a tooltip, use the following syntax:

You will need to have a funded Entropy {{< tooltip "account" >}} in order to progress with this tutorial.

Attempting to use a tooltip element that does not exist in the tooltip.html shortcode will cause the Hugo build to fail.

Support

All support tickets are handled in the Discussion tab of the github.com/entropyxyz/community repository.

Submitting a ticket

To submit a support ticket:

1. Head to the Discussion tab of the github.com/entropyxyz/community repository.
2. Select New discusison.
3. Next to Support click Get started.
4. Someone from Entropy will reach out to you within that thread for more details.

Discord

We do not use Discord for support tickets. If you receive a message about a support ticket from someone claiming to be from Entropy, this is likely a scam. All support tickets are handled publically through GitHub.

Contribute

We appreciate contributions of any size from everyone, from fixing typos to proposing substantial rewrites to aid clarity. Simply make a PR with your edits, and a member of the Entropy devrel team will review everything.

Writing docs

You can find all the docs in the /content folder. This content directory is structured the same as the website. The only caveats:

1. The docs.entropy.xyz homepage is controlled by ./content/_index.md.
2. Section indexes, like docs.entropy.xyz/concepts, are automatically generated by Hugo -- you do not need to directly edit the content of these pages. The content in the sub-pages controls the page snippets in these index pages. For example, the snippet for the Quickstart entry in docs.entropy.xyz/basics is generated from the lead variable within ./content/basics/quickstart.md. If a lead variable does not exist, Hugo generates a snippet from the main content of a sub-page.

License

• Most things in /content are licensed under MIT unless otherwise specified.
• The theme for this site is a modified version of Imfing's Hextra theme used under the MIT license.
• Hugo is licensed under the Apache 2.0 License.