search

entropyxyz / entropy-docs

Documentation for Entropy.
https://docs.entropy.xyz
GNU Affero General Public License v3.0
3 stars 2 forks source link

readme

Entropy Docs

This repository contains the documentation for the Entropy project (found in /docs) and all the build scripts to create the docs.entropy.xyz site. This repo also serves as the support hub for Entropy.

Project Board Issues MIT License

Table of contents

Run locally

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

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

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

  2. Install the dependencies for Docusaurus (pick one package manager process; do not run all three):

    # Using NPM
npm install
    # Using PNPM
pnpm install
    # Using Yarn
yarn

  3. Run the build scripts and run a local server:

    # Using NPM
npm run start
    # Using PNPM
pnpm run start
    # Using Yarn
yarn start

  4. Go to localhost:3000 in your browser.

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

The search bar does not work when running the website locally using this method. To interact with the search bar, you must Build the site.

Build

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

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

  2. Install the dependencies for Docusaurus (pick one package manager process; do not run all three):

    # Using NPM
npm install
    # Using PNPM
pnpm install
    # Using Yarn
yarn

  3. Run the build scripts:

    # Using NPM
npm run build 
    # Using PNPM
pnpm run build
    # Using Yarn
yarn build

Deploy

Deploying the site is done from the command-line:

GIT_USER=<GITHUB_USERNAME> USE_SSH=true yarn deploy

Troubleshooting

If the deploy doesn't work for whatever reason, try checking out to the gh-pages branch, pullling in the latest changes, and running the deploy command again:

git checkout gh-pages && git pull && checkout main && npm run start

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

Repository structure

File or directory Description
.docusaurus Configuration directory specific to Docusaurus. Holds themes and plugins for this site.
.git/ Stores Git version control information (ignore).
.github/ Directory for GitHub-specific configurations (ignore).
.gitignore File specifying files to be ignored by Git (ignore).
LICENSE File containing the license under which this project is distributed.
README.md This file.
blog/ Directory containing markdown files for Entropy Docs blog posts. This is currently unused.
docs/ Core directory containing markdown files for Entropy technical documentation.
docusaurus.config.js Main configuration file for this Docusaurus project.
package-lock.json (Generated file) Lists exact versions of dependencies used in this project.
package.json File specifying project dependencies and scripts.
sidebars.js File defining the navigation structure for the docs site. Docusaurus depends on this file.
src/ Source code directory for this Docusaurus project, specifically React components.
static/ Directory for static assets used by docs.entropy.xyz site (images, fonts, etc.).
tsconfig.json Configuration file for TypeScript (ignore).
yarn.lock Similar to package-lock.json. Lists exact versions of dependencies used in this project.

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 Issues in this repository.

Contribute

We appreciate contributions of any size from everyone, from fixing typos to proposing substantial rewrites to aid clarity. This section briefly describes how you can contribute to our documentation in four easy steps.

Getting started

  1. Fork this repository: Before making changes, you'll need to create a fork of our repository on GitHub. This creates a copy in your own account that you can modify.
  2. Clone your fork: Once you've forked our repository, clone your fork to your local machine. This will allow you to make changes locally.

Making changes

  1. Identify your contribution: Look through the documentation in the docs/ directory and find areas where you can improve the content, fix typos, or add new information.
  2. Edit files: Make the changes you'd like to see. Check out the Docusaurus documentation for any specific markdown rules you might not be aware of.

Submitting your changes

  1. Commit your changes: Commit your changes with a descriptive message explaining what you modified.
  2. Push your changes: Push your committed changes to your forked repository on GitHub.
  3. Create a pull request: On GitHub, navigate to your forked repository and create a pull request. This sends a notification to the Entropy Docs team about your proposed changes.

Review Process

  1. Receive review from the docs team: The Entropy docs team will review your pull request and may ask questions or suggest edits.
  2. Respond to feedback: Be prepared to discuss your changes and make adjustments based on the feedback provided.
  3. Your proposed changes are merged: Once your pull request is approved, we will merge your changes into the main branch.

Additional Tips

We appreciate your help in making our documentation even better. By following these guidelines, you can ensure a smooth and successful contribution process.

License