From b6bc79864528b920b96f894ee12e1b1860a2c01d Mon Sep 17 00:00:00 2001
From: Marc Garcia <garcia.marc@gmail.com>
Date: Sun, 28 Jan 2024 13:39:30 +0700
Subject: [PATCH] Updating README with new installation instructions

---
 README.md | 89 ++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 69 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 12770c0..9303f10 100644
--- a/README.md
+++ b/README.md
@@ -5,37 +5,75 @@ Web service that publishes a preview of a GitHub project documentation.
 The documentation itself has to be built during the project continuous
 integration and published as a GitHub actions artifact.
 
-Then, the repository can be configured to request a preview when
-a comment `/preview` is written in the pull request page. The request
-is made as en HTTP POST request, for example:
-
-```
-curl -X POST https://docs-previewer-server.com/preview/pandas-dev/pandas/56907/
+## Client installation
+
+To be able to use this service in your project, you need to have a CI
+job that looks like this:
+
+```yaml
+on: [ push, pull_request ]
+
+jobs:
+  doc:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+    steps:
+      # Instead of this step you may have a step to check out the repository,
+      # another to call `sphinx-build`, or anything that generates a directory
+      # with the html version of your website or documentation
+      - run: mkdir docs_dir && echo "Preview is working!" > docs_dir/index.html
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: docs_artifact
+          path: docs_dir
 ```
 
-This will cause the server to download the artifact and extract it, so it is
-available for example at https://docs-previewer-server.com/previews/56907/
-
-The server will automatically delete old previews.
+Then, you can add one action in your CI to for example publish the website or
+documentation of a pull request when a user writes a comment with the content
+`/preview`:
+
+```yaml
+on:
+  issue_comment:
+    types: created
+
+jobs:
+  previewer:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    if: github.event.issue.pull_request && github.event.comment.body == '/preview'
+    steps:
+      - uses: pandas-dev/github-doc-previewer@master
+        with:
+          # The server specified here has to explicitly allow your GitHub organization
+          previewer-server: "https://pandas.pydata.org"
+
+          # Note that this has to match with the name of the job where the
+          # `upload-artifact` action is called
+          artifact-job: "Build Documentation"
+```
 
-## Installation
+## Server Installation
 
-A package is provided for Debian based systems. It can be installed with
-the next command:
+Currently only packages for Debian are provided. The package can be installed
+using the next command:
 
 ```
-curl -sLO https://github.com/pandas-dev/github-doc-previewer/releases/download/v0.1.1/doc-previewer_0.1.1-1_amd64.deb \
-    && sudo dpkg -i doc-previewer_0.1.1-1_amd64.deb \
-    && rm doc-previewer_0.1.1-1_amd64.deb
+curl -sLO https://github.com/pandas-dev/github-doc-previewer/releases/download/v0.2.0/doc-previewer_0.2.0-1_amd64.deb \
+    && sudo dpkg -i doc-previewer_0.2.0-1_amd64.deb \
+    && rm doc-previewer_0.2.0-1_amd64.deb
 ```
 
-To start the server:
+To start the service:
 
 ```
-nohup doc-previewer > /var/log/doc-previewer.log 2>&1 &
+sudo systemctl enable doc-previewer.service
+sudo systemctl start doc-previewer.service
 ```
 
-## Configuration
+### Configuration
 
 A sample configuration file is next:
 
@@ -52,7 +90,7 @@ url = "https://doc-previewer.pydata.org/"
 [github]
 entrypoint = "https://api.github.com/repos/"
 token = "xxxxx"
-allowed_owners = [ "pydata", "pandas-dev" ]
+allowed_owners = [ "pandas-dev", "pydata" ]
 
 [log]
 level = "info"
@@ -60,3 +98,14 @@ format = "%a %{User-Agent}i"
 ```
 
 All the fields are optional except for the GitHub token, which is required.
+
+### Logging
+
+When a problem exists, the service will in general report it to the client.
+Checking the logs of the `github-doc-previewer` action run that failed may
+provide information on the cause of the problem. Errors will also be logged
+in the server, and can be checked using the standard journal logs:
+
+```bash
+journalctl -u doc-previewer.service
+```