Skip to content

Commit

Permalink
Updating README with new installation instructions
Browse files Browse the repository at this point in the history
  • Loading branch information
datapythonista committed Jan 28, 2024
1 parent e89e8f2 commit b6bc798
Showing 1 changed file with 69 additions and 20 deletions.
89 changes: 69 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -52,11 +90,22 @@ 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"
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
```

0 comments on commit b6bc798

Please sign in to comment.