Link project documentation (#2)

# Summary

- Added `.github/workflow/docs.yml`. Build documentation for errors and
check links in Pull Requests and on main.
- Updated `CHANGELOG.md`
- Added docs badge to `README.md`
- Updated documentation in `README.md` and `CONTRIBUTING.md`
- `tests` and `style` workflows ignore changes to `docs`

.github/workflows/docs.yml

@@ -0,0 +1,41 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    name: Test build docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: install requirements
+        run: |
+          python -im pip install --upgrade pip
+          python -im pip install .[docs]
+      - name: Build docs
+        run: |
+          python -m sphinx -W -n -b html -a docs docs/_build
+
+  linkcheck:
+    name: Linkcheck
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+      - name: install requirements
+        run: |
+          python -im pip install --upgrade pip
+          python -im pip install .[docs]
+      - name: Linkcheck docs
+        run: python -m sphinx -b linkcheck -a docs docs/_build/linkcheck

.github/workflows/style.yml

@@ -3,8 +3,12 @@ name: Code style
 on:
   push:
     branches: [main]
+    paths-ignore:
+      - "docs/**"
   pull_request:
     branches: [main]
+    paths-ignore:
+      - "docs/**"
 
 # Cancel concurent in-progress jobs or run on pull_request
 concurrency:

.github/workflows/tests.yml

@@ -2,13 +2,13 @@ name: Tests & Mypy
 
 on:
   push:
-    branches:
-      - main
+    branches: [main]
+    paths-ignore:
+      - "docs/**"
   pull_request:
-    branches:
-      - main
-
-# TODO: pages
+    branches: [main]
+    paths-ignore:
+      - "docs/**"
 
 jobs:
   mypy:
@@ -88,4 +88,3 @@ jobs:
           python -Im coverage report --show-missing --skip-covered --skip-empty --format=markdown >> $GITHUB_STEP_SUMMARY
           # Report in console
           python -Im coverage report --show-missing --skip-covered --skip-empty
-

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## [unreleased]
+
+- Added `py.typed` file.
+
 ## 0.1.0 - 2024-03-30
 
 - Initial release.

CONTRIBUTING.md

@@ -25,6 +25,10 @@ uninstall      Remove development environment
 ## Running the tests
 
 The tests require a new `p4d` server running in the backgound.
-To simplify the development, tests are runned in a docker container generated from this [Dockerfile](Dockerfile).
+To simplify the development,
+tests are runned in a docker container
+generated from the [Dockerfile](https://github.com/tahv/pyforce/blob/main/Dockerfile)
+at the root of this repo.
+
+The `make tests` target build the container and run the tests, with coverage, inside.
 
-This target `make tests` target build the container and run the tests + coverage inside.

README.md

@@ -6,6 +6,7 @@
 [![Linter - Ruff][ruff-badge]][ruff-repo]
 [![Types - Mypy][mypy-badge]][mypy-repo]
 [![CI - Tests][pyforce-workflow-tests-badge]][pyforce-workflow-tests]
+[![Documentation Status][pyforce-docs-badge]][pyforce-documentation]
 
 Python wrapper for Perforce p4 command-line client.
 
@@ -73,12 +74,11 @@ FStat(
 """
 ```
 
-The goal of Pyforce is not to be exhaustive. 
-It focuses on the most common `p4` commands, 
-but can execute more complexe commands by using `pyforce.p4`.
+Pyforce has functions for the most common `p4` commands
+but can execute more complexe commands with `pyforce.p4`.
 
-For example, Pyforce does not have a function to create a new client workspace, 
-but it is possible to create one with `pyforce.p4`.
+For example, pyforce doesn't have a function to create a new client workspace,
+here is how to create one using `pyforce.p4`.
 
 ```python
 import pyforce
@@ -107,16 +107,14 @@ Client(
 """
 ```
 
-<!--
 ## Documentation
 
-See [documentation]() for more details.
--->
+See pyforce [documentation](https://pyforce.readthedocs.io/en/latest) for more details.
 
 ## Contributing
 
 For guidance on setting up a development environment and contributing to pyforce,
-see the [Contributing](https://github.com/tahv/pyforce/blob/main/CONTRIBUTING.md) section.
+see the [Contributing](https://pyforce.readthedocs.io/en/latest/contributing.html) section.
 
 <!-- Links -->
 
@@ -126,9 +124,11 @@ see the [Contributing](https://github.com/tahv/pyforce/blob/main/CONTRIBUTING.md
 [python-version-badge]: https://img.shields.io/pypi/pyversions/pyforce-p4?logo=python&label=Python&logoColor=white
 [mypy-badge]: https://img.shields.io/badge/Types-Mypy-blue.svg
 [pyforce-workflow-tests-badge]: https://github.com/tahv/pyforce/actions/workflows/tests.yml/badge.svg
+[pyforce-docs-badge]: https://readthedocs.org/projects/pyforce/badge/?version=latest
 
 [pyforce-license]: https://github.com/tahv/pyforce/blob/main/LICENSE
 [ruff-repo]: https://github.com/astral-sh/ruff
 [pyforce-pypi]: https://pypi.org/project/pyforce-p4
 [mypy-repo]: https://github.com/python/mypy
 [pyforce-workflow-tests]: https://github.com/tahv/pyforce/actions/workflows/tests.yml
+[pyforce-documentation]: https://pyforce.readthedocs.io/en/latest

docs/conf.py

@@ -62,5 +62,5 @@
 # -- Options for HTML output -------------------------------------------------
 
 html_theme = "furo"
-html_static_path = ["_static"]
+# html_static_path = ["_static"]
 html_title = "Pyforce"

pyproject.toml

@@ -28,7 +28,7 @@ classifiers = [
 [project.urls]
 Github = "https://github.com/tahv/pyforce"
 Changelog = "https://github.com/tahv/pyforce/blob/main/CHANGELOG.md"
-# Documentation = ""
+Documentation = "https://pyforce.readthedocs.io/en/latest"
 
 [project.optional-dependencies]
 tests = ["pytest", "coverage"]