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

Minor Markdown improvements on packaging page #329

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Minor Markdown improvements on packaging page #329

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
31991bc
Minor Markdown improvement on packaging page
santisoler Jul 14, 2024
578f5e1
Merge branch 'main' into minor-md-style
flpm Sep 28, 2024
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
8 changes: 4 additions & 4 deletions package-structure-code/pyproject-toml-python-package-metadata.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,12 +139,12 @@ When you create your `pyproject.toml` file, there are numerous metadata fields t

[An overview of all of the project metadata elements can be found here.](https://packaging.python.org/en/latest/specifications/core-metadata/#project-url-multiple-use)

### Required fields for the [project] table
### Required fields for the `[project]` table

As mentioned above, your pyproject.toml file needs to have a **name** and **version** field in order to properly build your package:
As mentioned above, your `pyproject.toml` file needs to have a **`name`** and **`version`** field in order to properly build your package:

- Name: This is the name of your project provided as a string
- Version: This is the version of your project. If you are using a scm tool for versioning (using git tags to determine versions), then the version may be dynamic (more on that below).
- `name`: This is the name of your project provided as a string
- `version`: This is the version of your project. If you are using a SCM tool for versioning (using git tags to determine versions), then the version may be dynamic (more on that below).
Comment on lines 141 to +147
Copy link
Contributor

Choose a reason for hiding this comment

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

I'm curious - all these modifications will have an impact on the translation files (i.e. *.po). @flpm do you know if they get automagically updated or do we have to render them again? The way the translation works is that it searches for certain strings and transforms it to the provided translation so... if the original string is transformed, it won't detect the the translation.

Copy link
Contributor

Choose a reason for hiding this comment

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

Impacted PR is #340

Copy link
Member Author

Choose a reason for hiding this comment

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

Good question. I'm not sure, I'd have to try to see if there's any impact. Nonetheless, I think it's better to keep the fields [project], name and version in English, since they are part of the idioms of the pyproject.toml file. Using a translated version of them won't work.

Copy link
Contributor

@RobPasMue RobPasMue Jul 15, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Oh yeah, I completely agree with you on that! My comment was more directed to the fact that they original string was not MD styled - and thus it didn't show up with backticks in the translation file. Now that we added backticks I'm not sure whether the tools will still know that "this is the sentence to translate", or whether we have to manually update the file, or if it is automatically updated.

Copy link
Member Author

Choose a reason for hiding this comment

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

I see. Good point. I'm not familiar on how the .po files work. Do you know any docs I can read about them and how the translation setup works?

Copy link
Contributor

Choose a reason for hiding this comment

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

Thanks a lot for the explanation @flpm!

Copy link
Member Author

Choose a reason for hiding this comment

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

Thanks @flpm for the detailed explanation! It was very helpful.

I experimented with building the docs with and without the changes of this PR, and @RobPasMue you were right, they do impact the translations.

These are the translated docs (without these changes):
Screenshot from 2024-07-18 21-29-03

These are the translated docs (with these changes):

Screenshot from 2024-07-18 21-28-46

So, I think we could wait for #340 to be merged before merging this one. By then I'll update this branch and make the required changes in the .po file.

Copy link
Member Author

Choose a reason for hiding this comment

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

BTW, in case someone wants to build the translated docs we need to add a locale_dirs = ["locales/"] to the Sphinx config.py and to set RELEASE_LANGUAGES = ["es"] in the noxfile.py.

After that, running nox -s docs will build the English and Spanish docs. You can access the translated docs in the _build/html/es folder.

Copy link
Contributor

@RobPasMue RobPasMue Jul 18, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Hi @santisoler! Thanks for verifying :) The pyOpenSci team also has a dedicated nox command to build the translated docs directly. It's the following nox -s docs-live -- -D language=es. Plus, it is also pretty cool since any changes will rebuild the docs for you without having to do it yourself.

Copy link
Member Author

Choose a reason for hiding this comment

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

Nice! Good to know that, and thanks for sharing.

I'll make this PR a Draft so we don't merge it before #340 is merged.


### Optional fields to include in the `[project]` table

Expand Down