improve docs

.github/workflows/docs.yml

@@ -0,0 +1,53 @@
+name: docs_pages_workflow
+
+on: [pull_request]
+
+permissions:
+  pull-requests: write
+
+jobs:
+  build_docs_job:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v3
+        with:
+          python-version: 3.8
+
+      - name: Get pip cache dir
+        id: pip-cache
+        run: |
+          python -m pip install --upgrade pip
+          echo "dir={$(pip cache dir)}" >> $GITHUB_OUTPUT
+
+      - name: pip cache
+        uses: actions/cache@v3
+        with:
+          path: ${{ steps.pip-cache.outputs.dir }}
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/setup.py', '**/requirements.txt', '**/docs/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install docs requirements
+        run: |
+          python -m pip install -r docs/requirements.txt
+
+      - name: make the sphinx docs
+        run: |
+          make -C docs clean
+          make -C docs html
+
+      - uses: readthedocs/actions/preview@v1
+        with:
+          project-slug: "trlx"
+          project-language: "en"
+          # see: https://github.com/readthedocs/actions/tree/main/preview
+          # message-template (optional): Text message to be injected by the action in the Pull Request description. It supports the following placeholders to be replaced:
+          # {docs-pr-index-url}: URL to the root of the documentation for the Pull Request preview.
+          # platform (optional): Read the Docs Community (community) or Read the Docs for Business (business). (default: community)
+          # single-version (optional): Set this to 'true' if your project is single version, so we can link to the correct URL. (default: 'false')

.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
--   repo: https://github.com/pre-commit/pre-commit-hooks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.4.0
     hooks:
         - id: check-case-conflict
@@ -18,17 +18,24 @@ repos:
           args: [--fix=lf]
         - id: requirements-txt-fixer
         - id: trailing-whitespace
--   repo: https://github.com/psf/black
+  - repo: https://github.com/psf/black
     rev: 23.1.0
     hooks:
-    -   id: black
+      - id: black
         files: ^(trlx|examples|tests|setup.py)/
--   repo: https://github.com/pycqa/isort
+  - repo: https://github.com/pycqa/isort
     rev: 5.12.0
     hooks:
-    -   id: isort
+      - id: isort
         name: isort (python)
--   repo: https://github.com/pycqa/flake8
+  - repo: https://github.com/pycqa/flake8
     rev: 6.0.0
     hooks:
-    -   id: flake8
+      - id: flake8
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.2.2
+    hooks:
+      - id: codespell
+        args: [--ignore-words, dictionary.txt]
+        additional_dependencies:
+          - tomli

.readthedocs.yml

@@ -1,9 +1,25 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
 version: 2
 
+build:
+  os: "ubuntu-20.04"
+  tools:
+    python: "3.8"
+
+# Build documentation in the docs/ directory with Sphinx
 sphinx:
-  configuration: docs/source/conf.py
+  configuration: docs/conf.py
+  fail_on_warning: false
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+  - htmlzip
 
+# Optionally set the version of Python and requirements required to build your docs
 python:
-  version: 3.9
   install:
-  - requirements: docs/requirements.txt
+    - requirements: docs/requirements.txt

CHANGELOG.md

@@ -0,0 +1,11 @@
+# Change log
+
+Best viewed on [trlx.readthedocs.io](https://trlx.readthedocs.io/en/latest/changelog.html).
+
+<!--
+Remember to align the itemized text with the first line of an item within a list.
+-->
+
+## trlx 0.4.0 (2022-12-05)
+
+- python 3.8

CONTRIBUTING.md

@@ -2,7 +2,11 @@
 
 Looking to improve `trlX`? Thanks for considering!
 
-There are many ways to contribute, from writing tutorials in [Colab notebooks](https://colab.research.google.com) to improving the project's [documentation](https://trlx.readthedocs.io), submitting bug reports and feature requests, or even implementing new features themselves. See the outstanding [issues](https://github.com/CarperAI/trlx/issues) for ideas on where to begin.
+There are many ways to contribute, from writing tutorials in [Colab notebooks](https://colab.research.google.com) to improving the project's [documentation](https://trlx.readthedocs.io), to submitting bug reports and feature requests, or even implementing new features themselves. See the outstanding [issues](https://github.com/CarperAI/trlx/issues) for ideas on where to begin.
+
+- [Documentation Issues](https://github.com/CarperAI/trlx/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation)
+- [Bug Fixes](https://github.com/CarperAI/trlx/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
+- [Feature Requests](https://github.com/CarperAI/trlx/issues?q=is%3Aissue+is%3Aopen+label%3A%22feature+request%22)
 
 Here are some guidelines to help you get started 🚀.
 
@@ -16,40 +20,83 @@ To submit a bug report or a feature request, please open an [issue](https://gith
 
 Follow these steps to start contributing code:
 
+1. Setup your environment:
+
+```bash
+conda create -n trlx python=3.8 torch torch-cuda=11.7 -c pytorch -c nvidia
+git clone https://github.com/CarperAI/trlx
+cd trlx
+pip install -e ".[dev]"
+pre-commit install
+```
+
 1. Create your own [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo#forking-a-repository) of the repository and clone it to your local machine.
+
     ```bash
     git clone https://github.com/<YOUR-USERNAME>/trlx.git
     cd trlx
     git remote add upstream https://github.com/CarperAI/trlx.git
     ```
-2. Create a new branch for your changes and give it a concise name that reflects your contribution.
+
+1. Create a new branch for your changes and give it a concise name that reflects your contribution.
+
     ```bash
     git checkout -b <BRANCH-NAME>
     ```
-2. Install the development dependencies in a Python environment.
+
+1. Install the development dependencies in a Python environment.
+
     ```bash
     pip install -e ".[dev]"
     pre-commit install
     ```
-4. Implement your changes. Make small, independent, and well documented commits along the way (check out [these](https://cbea.ms/git-commit/) tips).
-5. Add unit tests whenever appropriate and ensure that the tests pass. To run the entire test suite, use the following command from within the project root directory.
+
+install pre-commit
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+bonus: force run pre-commit on all the files
+
+```bash
+pre-commit run --all-files
+```
+
+1. Implement your changes. Make small, independent, and well documented commits along the way (check out [these](https://cbea.ms/git-commit/) tips).
+
+1. Add unit tests whenever appropriate and ensure that the tests pass. To run the entire test suite, use the following command from within the project root directory.
+
     ```bash
     pytest
     ```
+
     For changes with minimal project scope (e.g. a simple bug fix), you might want to run the unit tests for just a specific test file instead:
+
     ```bash
     pytest -vv -k "<TEST-FILE-NAME>"
     ```
-5. Commit your final changes. Our `pre-commit` hooks will automatically run before each commit and will prevent you from committing code that does not pass our style and linter checks. They'll also automatically format your code! To run these manually, use the following command:
+
+1. Commit your final changes. Our `pre-commit` hooks will automatically run before each commit and will prevent you from committing code that does not pass our style and linter checks. They'll also automatically format your code! To run these manually, use the following command:
+
     ```bash
     pre-commit run --all-files
     ```
 
-6. Push the changes to your fork.
+1. Push the changes to your fork.
 
 Finally ... 🥁 ... Create a [pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) to the `trlX` repository! Make sure to include a description of your changes and link to any relevant issues.
 
-> __Tip__: If you're looking to introduce an experimental feature, we suggest testing the behavior of your proposed feature on some of the existing [examples](https://github.com/CarperAI/trlx/tree/master/examples), such as [random walks](https://github.com/CarperAI/trlx/blob/master/examples/randomwalks). This will help you get a better sense of how the feature would work in practice and will also help you identify any potential flaws in the implementation.
+> **Tip**: If you're looking to introduce an experimental feature, we suggest testing the behavior of your proposed feature on some of the existing [examples](https://github.com/CarperAI/trlx/tree/master/examples), such as [random walks](https://github.com/CarperAI/trlx/blob/master/examples/randomwalks). This will help you get a better sense of how the feature would work in practice and will also help you identify any potential flaws in the implementation.
+
+## Tips & Tricks
+
+Set transformers verbosity level
+
+```bash
+TRANSFORMERS_VERBOSITY=error
+```
 
 ## Asking questions
 
@@ -63,4 +110,4 @@ This project adheres to the [Contributor Covenant Code of Conduct](https://githu
 
 By contributing, you agree that your contributions will be licensed under its MIT License.
 
-# Thank you for your contribution 🐠!
+## Thank you for your contribution! 🐠

LICENSE

@@ -1,4 +1,4 @@
-MIT License
+# MIT License
 
 Copyright (c) 2022 CarperAI
 

README.md

@@ -1,3 +1,7 @@
+![TRLX](./docs/_static/apple-touch-icon-114x114.png)
+
+[docs-image]: https://readthedocs.org/projects/trlX/badge/?version=latest
+[docs-url]: https://trlX.readthedocs.io/en/latest/?badge=latest
 
 [![DOI](https://zenodo.org/badge/545104023.svg)](https://zenodo.org/badge/latestdoi/545104023)
 
@@ -39,25 +43,25 @@ For more usage see [examples](./examples). You can also try the colab notebooks
 
 You can train a model using a reward function or a reward-labeled dataset.
 
-#### Using a reward function
+### Using a reward function
 
 ```python
 trainer = trlx.train('gpt2', reward_fn=lambda samples, **kwargs: [sample.count('cats') for sample in samples])
 ```
 
-#### Using a reward-labeled dataset
+### Using a reward-labeled dataset
 
 ```python
 trainer = trlx.train('EleutherAI/gpt-j-6B', dataset=[('dolphins', 'geese'), (1.0, 100.0)])
 ```
 
-#### Trainers provide a wrapper over their underlying model
+### Trainers provide a wrapper over their underlying model
 
 ```python
 trainer.generate(**tokenizer('Q: Who rules the world? A:', return_tensors='pt'), do_sample=True)
 ```
 
-#### Save the resulting model to a Hugging Face pretrained language model. (Ready to upload to the Hub!)
+### Save the resulting model to a Hugging Face pretrained language model. (Ready to upload to the Hub!)
 
 ```python
 trainer.save_pretrained('/path/to/output/folder/')

dictionary.txt

@@ -0,0 +1,2 @@
+rouge
+sart

docs/Makefile

@@ -5,7 +5,7 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
+SOURCEDIR     = .
 BUILDDIR      = build
 
 # Put it first so that "make" without argument is like "make help".

docs/README.md

@@ -0,0 +1,5 @@
+# How To build the documentation
+
+```bash
+make -c docs html
+```

docs/_static/style.css

@@ -0,0 +1,26 @@
+@import url("theme.css");
+
+:root {
+  --block-bg-opacity: .5;
+}
+
+.wy-side-nav-search {
+  background-color: #fff;
+}
+
+.getting-started {
+  background-color: rgba(78, 150, 253, var(--block-bg-opacity));
+}
+
+.user-guides {
+  background-color: rgba(0, 169, 154, var(--block-bg-opacity));
+}
+
+.developer-docs {
+  background-color: rgba(171, 0, 182, var(--block-bg-opacity));
+}
+
+.key-ideas
+{
+  border: 0px
+}

docs/_templates/layout.html

@@ -0,0 +1,2 @@
+{% extends "!layout.html" %}
+{% set css_files = css_files + ["_static/style.css"] %}

docs/build.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+`which sphinx-build` -T -E -b html -d _build/doctrees-readthedocs -D language=en . _build/html

docs/changelog.md

@@ -0,0 +1,2 @@
+```{include} ../CHANGELOG.md
+```