Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README with clearer instructions for running the server #94

Open
wants to merge 2 commits into
base: develop
Choose a base branch
from

Conversation

doomuch
Copy link

@doomuch doomuch commented Jun 18, 2024

Problem

While trying to get the readium-go-toolkit server running locally, I encountered two main pain points:

  1. The publication-path specified in the example config file (./publications) doesn't match the actual location of the test publications in the repo (./test). This caused some confusion and lost time trying to troubleshoot why no publications were being served.

  2. The current README lacks clear information about what endpoints are available and how to interact with them to retrieve publication data. As a new user, I had to dig through the code to understand the API surface.

Solution

This PR updates the README to address these issues and smooth out the onboarding process for new developers:

  1. Adds a note in the "Running the server" section calling out the publication-path discrepancy and providing instructions on how to resolve it
  2. Introduces a new "Accessing a publication" section with step-by-step examples of how to hit the /list.json, /manifest.json, and asset endpoints to retrieve publication data
  3. Includes a comment in the example config file about updating publication-path to ./test when using the provided test publications

Benefits

  • Reduces confusion and frustration when first trying to run the server locally
  • Provides a clear "happy path" for getting up and running with the API and exploring the functionality
  • Improves the overall developer experience and onboarding process for the project

@chocolatkey
Copy link
Member

chocolatkey commented Jul 15, 2024

Hi @doomuch , sorry about the delay in response, I was on a trip and was not available here. First of all, thanks very much for interest in helping with the docs, that's not my strong point. However, I was planning to remove the cmd/server program in a future commit, in favor of the rwp program's serve function, which is effectively replacing & improving it, save for a few things that I don't think should be decided by this implementation (e.g. Sentry as the error reporting service).

I think your documentation could be adapted to the rwp serve command as well. Let me know what you think, I can also try and work on that.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants