Minor Markdown improvements on packaging page #329
Conversation
Apply some minor improvements to the Markdown syntax in the pages instruction on how to create the `pyproject.toml` file.
|
|
||
| ### 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). |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
Thanks a lot for the explanation @flpm!
There was a problem hiding this comment.
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):
These are the translated docs (with these changes):
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
|
hi @santisoler @flpm @RobPasMue this pr has been open for some time. I didn't review it as I thought it was a translation-related pr. but maybe I should review it now! Is there anything holding us back from a review and merge? i'd love to merge it this week and open any issues if need be around it! but please do let me know. |
|
Hi @lwasser. Merging this PR would force us to update the translation files that are being created in #340. Since this PR is making changes to the English text, the translations will fail to find the original text to translate. That's why I made this PR a Draft PR in order to wait for #340 to be merged first, and then update the translations here. See #329 (comment) and #329 (comment) for reference. But, since the changes here are quite small, I think we can do this the other way around: merge this PR first, and then apply the required modifications to the translations in #340. I'm willing to apply those changes in #340. |
|
@santisoler thank you for that clarification!! Let's see what @RobPasMue and @flpm would like to do. I'm open to doing whatever makes life easier for everyone here!! |
|
Yes, the changes are small and we held this one for too long. Let's merge this one first, I will take care of the update of the translation files after I merge the other PR. |
|
ok fantastic! i'll merge it now! i'm just trying to clean up some of the older pr's across our organization in the spirit of the new year coming up!! thank you all for all of the work done here!! |
|
@all-contributors please add @santisoler for code, review |
|
I've put up a pull request to add @santisoler! 🎉 |
Apply some minor improvements to the Markdown syntax in the pages instruction on how to create the
pyproject.tomlfile.This PR was created during SciPy2024 sprints.
TODO