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.

Sign up for GitHub

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

Jump to bottom

docs: Improve contributing docs #5708

Merged
merged 6 commits into from
Jun 4, 2022
Merged

docs: Improve contributing docs #5708

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
48acd0f
docs: contributing doc: paste-able commands
juhoautio May 27, 2022
e654257
Comment about keeping docs in sync manually
juhoautio May 30, 2022
9cbbc07
Local dev requires Python 3.8+
juhoautio May 30, 2022
0a28e75
Split html comments to lines – does this fix hugo build?
juhoautio May 30, 2022
2f617c2
Try to bring back contributing page as it disappeared :)
juhoautio May 30, 2022
be182a4
Capitalize: "Poetry"
juhoautio May 30, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 9 additions & 7 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
<!-- The content of this file is manually kept in sync with docs/contributing.md. There are formatting differences because this file uses plain markdown. -->

# Contributing to Poetry

First off, thanks for taking the time to contribute!
Expand Down Expand Up @@ -107,8 +109,8 @@ You will need Poetry to start contributing on the Poetry codebase. Refer to the
You will first need to clone the repository using `git` and place yourself in its directory:

```bash
$ git clone git@github.com:python-poetry/poetry.git
$ cd poetry
git clone git@github.com:python-poetry/poetry.git
cd poetry
```

> **Note:** We recommend that you use a personal [fork](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo) for this step. If you are new to GitHub collaboration,
Expand All @@ -118,15 +120,15 @@ Now, you will need to install the required dependency for Poetry and be sure tha
tests are passing on your machine:

```bash
$ poetry install
$ poetry run pytest tests/
poetry install
poetry run pytest tests/
```

Poetry uses [mypy](https://github.com/python/mypy) for typechecking, and the CI
will fail if it finds any errors. To run mypy locally:

```bash
$ poetry run mypy
poetry run mypy
```

Poetry uses the [black](https://github.com/psf/black) coding style and you must ensure that your
Expand All @@ -139,13 +141,13 @@ To make sure that you don't accidentally commit code that does not follow the co
install a pre-commit hook that will check that everything is in order:

```bash
$ poetry run pre-commit install
poetry run pre-commit install
```

You can also run it anytime using:

```bash
$ poetry run pre-commit run --all-files
poetry run pre-commit run --all-files
```

Your code must always be accompanied by corresponding tests, if tests are not present your code
Expand Down
16 changes: 9 additions & 7 deletions docs/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
<!-- The content of this file is manually kept in sync with ../CONTRIBUTING.md. There are formatting differences because this file uses Hugo templating. -->
Copy link
Contributor Author

@juhoautio juhoautio May 30, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This could be mentioned:

When you make a PR, a github action runs automatically and deploys a test website using your branch.

But it would be good to know also how to build & view the docs locally. For example adding this comment here in a "hugo template file", I'm not sure how it's going to look like when it's live before the gh action has finished deploying the changes that I pushed.

I can see that workflows/docs.yml is for example cloning another repo, the python-poetry/website. But I'm wondering if there's any lightweight way to see the files from under docs/ rendered locally.

This is what I tried:

brew install hugo
hugo -v --minify

But not sure what to do, as I got this:

Error: Unable to locate config file or config directory. Perhaps you need to create a new site.
       Run `hugo help new` for details.

Total in 1 ms

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can clone the repo, use provided README file to set it up (granted, it's not the best manual, I am working on something better) and see it locally.

Copy link
Contributor Author

@juhoautio juhoautio May 30, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

I had to run npm install before npm run dev – so that's missing from https://github.com/python-poetry/website#local-development. EDIT: I should try this again from scratch, but I don't think that npm run dev is at least needed at all..

I get this in the terminal:

rollup v2.50.5
bundles src/app.js → assets/assets/app.js...

Where can I view the docs?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It should be in the public/ folder as a pile of files -- that being said, note that the action requires someone to add the Documentation tag, and presently that has to be a member of the Poetry team. It's really meant as a way for the team to view the rendered docs without a local clone, as opposed to a way to give feedback to the PR author.

We should focus on documenting how to build the website locally for this use case.

Copy link
Contributor Author

@juhoautio juhoautio May 31, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I figured it out. Previously I was trying poetry run python bin/website build --local ./poetry which lead into some errors, and I ignored them – I shouldn't have :) Of course I didn't have ./poetry , I have ../poetry.

So, this worked:

cd website
poetry run python bin/website build --local ../poetry
hugo server -w

Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)

(btw: -w, --watch watch filesystem for changes and recreate as needed (default true))

And that answered my question about "Where can I view the docs?".

This seems to be needed to apply changes without restarting the Hugo server:

hugo server --disableFastRender

But I still need to manually run poetry run python bin/website build --local ../poetry to apply any changes, which is natural because there's a script that copies files from ../poetry/docs to content/docs/. Looks like the file contents are not changed at all so probably automatic live reloading can be achieved by symlinking, for example.

I can volunteer to document this in the contributing docs if it helps, let me know.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

checkout latest update to package.json and npm scripts provided in website. you can now just run npm run dev and both npm and hugo will run. There is also Makefile providing ready to use scripts for that. I don't see need for all this to be in Poetry contributing.md. Those are separate projects.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could it be somehow documented how to test docs changes locally when contributing to poetry? If I understood correctly the website README instructions work out of the box only for the latest docs in poetry main branch, not my local poetry dev project.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Related: python-poetry/website#48


---
title: "Contributing to Poetry"
draft: false
Expand Down Expand Up @@ -122,8 +124,8 @@ You will need Poetry to start contributing on the Poetry codebase. Refer to the
You will first need to clone the repository using `git` and place yourself in its directory:

```bash
$ git clone git@github.com:python-poetry/poetry.git
$ cd poetry
git clone git@github.com:python-poetry/poetry.git
cd poetry
```

{{% note %}}
Expand All @@ -135,15 +137,15 @@ Now, you will need to install the required dependency for Poetry and be sure tha
tests are passing on your machine:

```bash
$ poetry install
$ poetry run pytest tests/
poetry install
poetry run pytest tests/
```

Poetry uses [mypy](https://github.com/python/mypy) for typechecking, and the CI
will fail if it finds any errors. To run mypy locally:

```bash
$ poetry run mypy
poetry run mypy
```

Poetry uses the [black](https://github.com/psf/black) coding style and you must ensure that your
Expand All @@ -156,13 +158,13 @@ To make sure that you don't accidentally commit code that does not follow the co
install a pre-commit hook that will check that everything is in order:

```bash
$ poetry run pre-commit install
poetry run pre-commit install
```

You can also run it anytime using:

```bash
$ poetry run pre-commit run --all-files
poetry run pre-commit run --all-files
```

Your code must always be accompanied by corresponding tests, if tests are not present your code
Expand Down