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.
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