bookwyrm-social/documentation

How to use BookWyrm

documentation's Issues

Add linters

markdown formatting not translating to documentation site

This indentation to make a nested list doesn't work for the rendered version.
Also I think there should be a colon after "formatting" anyway.

Installing in Production page - using a reverse proxy 404 not found

Hello, I'm following the instructions on https://docs.joinbookwyrm.com/install-prod.html to start my own bookwyrm instance.

In the nginx configuration section it mentions to look at https://docs.joinbookwyrm.com/using-a-reverse-proxy.html if there is another web server running, however the page does not exist.

The file exists so I think it's just a matter of correcting the web page link?

https://github.com/bookwyrm-social/documentation/blob/main/content/running_bookwyrm/reverse-proxy.md

Example data in developer environment

hi! I was hoping to tweak author and/or book pages in response to some URL ideas (like in BookWyrm issue 1585). I set up the developer environment then concluded that there aren't any preset book or author pages and that the only way to add this information is via an authenticated user who has at least editor-level permissions. It seems like this would require setting up email verification. If I just want to see a representative book page, is there a recommended method for adding an example book (with an author) and/or user? If so, it occurred to me that this could be included in the documentation, perhaps in the permissions or developer environment pages. I apologize if this has been addressed elsewhere. Thanks!

add info for admins on managing federation

e.g. bookwyrm-social/bookwyrm#2950

Add new instance to offical list

https://bookwyrm.tech/ is ready to start accepting new users.

Code blocks won't render

Compare the source content with the live site

documentation/content/running_bookwyrm/install-prod.md

Lines 53 to 65 in bc50051

	## Configure your instance
	- Register a user account in the application UI
	- Make your account a superuser (warning: do *not* use django's `createsuperuser` command)
	- On your server, open the django shell
	`./bw-dev shell`
	- Load your user and make it a superuser
	```python
	from bookwyrm import models
	user = models.User.objects.get(id=1)
	user.is_staff = True
	user.is_superuser = True
	user.save()
	```

Documentation update + certbot error

Missed the correct repo the first time bookwyrm-social/bookwyrm#3148

Automatic deployment is github actions

Document processes required for PRs that change the DB structure

In the "Developer Environment" page there's a (very helpful!) list of commands to run to set up your environment. It may be helpful to add something somewhere about what to do if your PR is going to change the database structure. This could include:

• running docker-compose run --rm web python manage.py makemigrations before docker-compose run --rm web python manage.py migrate
• checking in your final clean migration files
• merging migrations if necessary
• preferred minimum tests ("anything that posts to a model" for example)

"Developer Environment" may not be the most sensible place for this, possibly it needs its own section I'm not sure.

Missing favicon

This should be very easy to fix! It just needs favicons.

"Contribute to this page" link points to the wrong repo

There's this "Contribute to this page" link in the footer at https://docs.joinbookwyrm.com that points to https://github.com/bookwyrm-social/join-bookwyrm. It should point to this repo instead.

Add instructions for enabling intellisense to dev environments

From a closed PR in the main repository:

I think a better way to solve this ... is to use Visual Studio Code Dev Containers. I haven't previously been using this, but I've just set it up and it seems to work pretty well. Basically you install the plugin and then it mounts your local dev environment as a volume so that changes are made both inside and outside the running container. Since all the requirements are installed in the container, your VS Code can then go ahead and use intellisense for auto-completion and so on.

It requires a fairly simple .devcontainer/devcontainer.json file:

{
	"name": "Bookwyrm Development",
	"dockerComposeFile": ["../docker-compose.yml"],
	"service": "web",
	"workspaceFolder": "/app",
	 "forwardPorts": [1333, 8888]
}

Originally posted by @hughrun in bookwyrm-social/bookwyrm#2653 (comment)

Add Accessibility and/or Inclusive Design section(s) to Style Guide

"Inclusive design" might be more ...inclusive, but on the other hand "Accessibility" is a widely understood term in the context of web design.

Having just contributed an (excessively large, whoops sorry) PR, I'm thinking of some of the things that were helpful to be told or to work out that aren't currently in the Contributing docs. One thing I had some awareness of but wasn't sure whether I was doing properly is good practice for accessibility. There are already some good tips on the main repository, but not explicitly in the docs:

• Inclusive design checklist
• PR for Better forms which lists some helpful principles. This presumably fixed things at the time but perhaps having something in the docs will prevent future errors sneaking in?
• This PR for accessibility fixes suggests there is some automatic linting for accessibilty, but it's not clear whether that is still the case, nor what it's looking for

Possibly included in this section (if it's a big "inclusive design" section), or possibly listed separately, should also be something around internationalisation and what to look out for to make sure you're doing it properly (e.g. I got caught a couple of times putting in a {% trans %} tag without {% load i18n %} and then getting errors).

Happy to draft something for a PR if you agree this would be helpful.

Fix proxy_pass location / for docker nginx

https://github.com/bookwyrm-social/documentation/blob/main/content/running_bookwyrm/reverse-proxy.md
in docker-compose.yml is:

version: '3'

services:
  nginx:
    image: nginx:latest
    restart: unless-stopped
    ports:
       - "8001:8001"

so in nginx should be not 8000 but:

    location / {
        proxy_pass http://localhost:8001;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
    }

Local Dev first setup should mention turning off https to prevent CSRF problems

When I follow the current instructions I get all the way through and find that I can't do https connections to my local machine.
Http seems to work though.
When I register with the admin key, I get blocked because of a CSRF warning.

I found that if I go into the .env and change USE_HTTPS=true to USE_HTTPS=false I am able to complete initial admin account registration.

dockerless instructions updates

Update this line to remove the trailing slash:

Replace /app/ with your install directory /opt/bookwyrm/ everywhere in the file (including commented out)

With

Replace /app with your install directory /opt/bookwyrm everywhere in the file (including commented out)

Also,
I think this line can be taken out. The current configuration file has both server blocks enabled.

Uncomment lines 18 through 50 to enable forwarding to HTTPS. You should have two server blocks enabled

External Storage instructions work with Linode/Akamai

When I first installed bookwyrm, I could not get External Storage to work with Linode (now called Akamai)'s object storage. I followed the instructions, and tried various tweaks based on previous experience using Linode's Object Storage in place of AWS S3 for other things, but nothing worked.

Now I am running bookwyrm 0.6.4 and decided to try setting it up again. This time following the instructions in the bookwyrm documentation worked perfectly. yay!

Error deploying docs site

Hi @bookwyrm-social/code-review if someone smarter than me can work out why this is happening I would be most grateful!

Per the last PR that I pulled in, we have a new GitHub action to build the site before it is deployed to the web server (previously it just deployed, without rebuilding). All is well, until we run python generate.py which should compile the site including translations, but instead we get:

Generating site/moderation.html
  File "/home/runner/work/documentation/documentation/generate.py", line 150, in <module>
    data = get_site_data(SLUG, locale["code"], content_path)
  File "/home/runner/work/documentation/documentation/generate.py", line 76, in get_site_data
    subcategories.sort(key=lambda v: v.get("Order", -1))
TypeError: '<' not supported between instances of 'str' and 'int'
Generating site/updating.html

I cannot replicate this error on my local machine, and I can't work out where the str might be coming from - I assume this should sort each subcategory by Order value.

Broken update documentation link

BookWyrm instances running on v0.3.x can't access the update documentation via dashboard anymore.

https://docs.joinbookwyrm.com/updating-your-instance.html is now https://docs.joinbookwyrm.com/updating.html

Is it possible to configure a redirect? Preferably using a HTTP redirect status code.

Alternatively, adding a minimal HTML page with https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#examples using 0 seconds?

bw-dev commands

Provide full documentation of all ./bw-dev commands.

I can be assigned to this.

Documentations says nothing about the different IDs

And as I am tired of explaining, I started to write down what every ID is representing, how they work and so on.

I started to write them down here and when finished I would do a pull request.
https://github.com/jaschaurbach/documentation/tree/explanation-of-different-IDs

Document flower / celery

Given the current stress on the system caused by an influx of corporate social media people, it might be helpful to document for admins where to inspect the queue of currently pending jobs.

This means, using a flower UI to see celery jobs.

posted this issue in wrong folder.. but cant delete. sorry.