From d791a4bb53beabc3258799298e4d57f3efed516b Mon Sep 17 00:00:00 2001 From: Subhash Bhushan Date: Wed, 3 Apr 2024 08:02:12 -0700 Subject: [PATCH] Deploy basic documentation to Github Pages --- .github/workflows/ci.yml | 23 ++++++++ docs/community/contributing.md | 98 ++++++++++++++++++++++++++++++++++ docs/community/index.md | 5 ++ docs/index.md | 3 ++ mkdocs.yml | 34 +++++++++++- 5 files changed, 162 insertions(+), 1 deletion(-) create mode 100644 docs/community/contributing.md create mode 100644 docs/community/index.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fb38b4f3..0d2e50be 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -6,6 +6,9 @@ on: pull_request: branches: [main] +permissions: + contents: write + jobs: test: runs-on: ubuntu-latest @@ -104,3 +107,23 @@ jobs: REDIS_HOST: localhost # The default Redis port REDIS_PORT: ${{ job.services.redis.ports[6379] }} + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Configure Git Credentials + run: | + git config user.name github-actions[bot] + git config user.email 41898282+github-actions[bot]@users.noreply.github.com + - uses: actions/setup-python@v5 + with: + python-version: 3.x + - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV + - uses: actions/cache@v4 + with: + key: mkdocs-material-${{ env.cache_id }} + path: .cache + restore-keys: | + mkdocs-material- + - run: pip install mkdocs-material + - run: mkdocs gh-deploy --force diff --git a/docs/community/contributing.md b/docs/community/contributing.md new file mode 100644 index 00000000..012eef39 --- /dev/null +++ b/docs/community/contributing.md @@ -0,0 +1,98 @@ +# Contribute to Protean + +Thank you for considering contributing to Protean! + +## First time local setup + +- Download and install [git](https://git-scm.com/downloads). +- Configure git with your `username`_ and `email`. + +```sh +$ git config --global user.name 'your name' +$ git config --global user.email 'your email' +``` + +- Make sure you have a [GitHub account](https://github.com/join). +- Fork Protean to your GitHub account by clicking the [fork](https://github.com/proteanhq/protean/fork) button. +- [Clone](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo#step-2-create-a-local-clone-of-your-fork) the main repository locally. + +```sh +$ git clone https://github.com/proteanhq/protean +$ cd protean +``` + +- Add your fork as a remote to push your work to. Replace `username` with your GitHub username. This names the remote "fork", the default Protean remote is "origin". + +```sh +$ git remote add fork https://github.com/{username}/protean +``` + +- [Create and activate virtualenv](https://docs.python.org/3/library/venv.html#creating-virtual-environments). + +```sh +$ python3 -m venv .venv +$ source .venv/bin/activate +``` + +- Install the development dependencies. + +```sh +$ poetry install --with dev,test,docs,types --all-extras +``` + +- Install the pre-commit hooks. + +```sh +$ pre-commit install --install-hooks +``` + +## Start coding + +- Create a branch to identify the issue you would like to work on. If + you're submitting a bug or documentation fix, branch off of the + latest ".x" branch. + +```sh +$ git fetch origin +$ git checkout -b your-branch-name origin/0.11.x +``` + +If you're submitting a feature addition or change, branch off of the + "main" branch. + +```sh +$ git fetch origin +$ git checkout -b your-branch-name origin/main +``` + +- Using your favorite editor, make your changes, [committing as you go]( + https://afraid-to-commit.readthedocs.io/en/latest/git/commandlinegit.html#commit-your-changes). +- Include tests that cover any code changes you make. Make sure the test fails +without your patch. Run the tests as described below. +- Push your commits to your fork on GitHub and [create a pull request]( + https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/ + proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). +Link to the issue being addressed with `fixes #123` or `closes #123` in the pull request. + +```sh +$ git push --set-upstream fork your-branch-name +``` + +## Running Tests + +Run the basic test suite with: + +```sh +$ protean test +``` + +This runs the basic tests for the current environment, which is usually sufficient. If you want to run +the full test suite, you can sep up dependent services locally with docker: + +```sh +$ make up +$ protean test -c FULL +``` + +Running a full test will also generate a coverage report as part of test output. Writing tests for lines +that do not have coverage is a great way to start contributing. diff --git a/docs/community/index.md b/docs/community/index.md new file mode 100644 index 00000000..95c25534 --- /dev/null +++ b/docs/community/index.md @@ -0,0 +1,5 @@ +# Community + +## Get Involved + +[Contribute to Protean](contributing.md) \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 92fa13f3..b16a4ed5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,6 +2,9 @@ *Framework for Event-driven Applications - build to last, batteries included* + + + --- **Documentation**: https://docs.proteanhq.com diff --git a/mkdocs.yml b/mkdocs.yml index 4b7e414b..ab94cb9a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,3 +1,35 @@ site_name: Protean +site_url: https://docs.proteanhq.com +repo_name: proteanhq/protean +repo_url: https://github.com/proteanhq/protean theme: - name: material \ No newline at end of file + name: material + palette: + - media: '(prefers-color-scheme: light)' + scheme: default + toggle: + icon: material/lightbulb + name: Switch to dark mode + - media: '(prefers-color-scheme: dark)' + scheme: slate + toggle: + icon: material/lightbulb-outline + name: Switch to light mode + features: + - navigation.instant + - navigation.instant.prefetch + - navigation.instant.progress + - navigation.tracking + - navigation.tabs + - navigation.tabs.sticky + - navigation.sections + - navigation.path + - navigation.prune + - navigation.indexes + - toc.follow + - navigation.top +nav: + - Protean: index.md + - Community: + - community/index.md + - community/contributing.md \ No newline at end of file