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.

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

[Docs] Acknowledge the files created as side effects after running commands #4201

Merged
merged 7 commits into from
Feb 5, 2024
Merged

[Docs] Acknowledge the files created as side effects after running commands #4201

merged 7 commits into from
Feb 5, 2024

Conversation

VladimirFokow
Copy link
Contributor

@VladimirFokow VladimirFokow commented Feb 1, 2024

Summary of changes

Preview

Partially solves #4198 - describes this behavior in the docs

  • is helpful for newcomers: acknowledges these files - now their creation is not a surprise
  • and a quick suggestion what to do with these auto-generated files (add to .gitignore)

@VladimirFokow VladimirFokow changed the title [Docs] #4198 acknowledged the side effects of running said commands [Docs] acknowledged the side effects of running commands (issue #4198) Feb 1, 2024
@VladimirFokow VladimirFokow changed the title [Docs] acknowledged the side effects of running commands (issue #4198) [Docs] Acknowledge the files created as side effects of running commands Feb 1, 2024
@VladimirFokow VladimirFokow changed the title [Docs] Acknowledge the files created as side effects of running commands [Docs] Acknowledge the files created as side effects after running commands Feb 1, 2024
- added the link to the issue
- text formatting & rewording
@abravalheri
Copy link
Contributor

abravalheri commented Feb 5, 2024

Hi @VladimirFokow, thank you very much for working on this.

Since we are talking about the quickstart page (and not a page that describes in depth the build process), I think it would be good to summarise the proposed content.

How about something along the lines:

.. note::
   During the build process - which is also triggered when you install the project from source code,
   e.g. ``pip install -e .`` - some directories hosting build artefacts and cache files may be
   created, such as ``build``, ``dist``, ``*.egg-info`` [#cache]_.
   You can configure your version control system to ignore them
   (see `GitHub's .gitignore template <https://github.com/github/gitignore/blob/main/Python.gitignore>`_
   for an example).

?

Then probably I would add a footnote saying something like:

.. [#cache]
   If you feel that caching is causing problems to your build specially after changes in the
   configuration files, consider removing ``build``, ``dist``, ``*.egg-info`` before
   rebuilding or installing your project.

@VladimirFokow
Copy link
Contributor Author

VladimirFokow commented Feb 5, 2024

Implemented this.
(& corrected a typo in the previous section: "file in file in your repository")

Now the pip install -e . command confusingly wraps onto the next line on my screen (the dot is on the next line).

I suggest:

.. note::

    During the build process from source code (for example, by ``pip install -e .`` or ``python -m build``)
    some directories hosting ...

@abravalheri
Copy link
Contributor

abravalheri commented Feb 5, 2024

Thank you, the suggestion looks good.

docs/userguide/quickstart.rst Outdated Show resolved Hide resolved
docs/userguide/quickstart.rst Outdated Show resolved Hide resolved
docs/userguide/quickstart.rst Outdated Show resolved Hide resolved
@abravalheri abravalheri merged commit f3ae5d6 into pypa:main Feb 5, 2024
2 of 18 checks passed
@abravalheri
Copy link
Contributor

Thank you very much!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants