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

Explain specific requirements for Markdown descriptions #522

Merged
merged 2 commits into from
Jun 15, 2018
Merged

Explain specific requirements for Markdown descriptions #522

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
44e1ad0
Explain specific requirements for Markdown descriptions
pgadige Jun 13, 2018
96d8d32
Rephrase and change to lowercase directive
pgadige Jun 13, 2018
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
21 changes: 21 additions & 0 deletions source/guides/making-a-pypi-friendly-readme.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,27 @@ Set the value of ``long_description`` to the contents (not the path) of the READ
Set the ``long_description_content_type`` to an accepted ``Content-Type``-style value for your README file's markup,
such as ``text/plain``, ``text/x-rst`` (for reStructuredText), or ``text/markdown``.

.. Note:: If you're using GitHub-flavored Markdown to write a project's description, ensure you upgrade
Copy link
Member

Choose a reason for hiding this comment

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

minor nit: use lowercase directive (like rest of file) + move statement to a new line for clarity.

.. note:: 

   If you're using GitHub-flavored Markdown to write a project's description, ensure you 
   upgrade the following tools:

the following tools:

.. code-block:: bash

python3 -m pip install --user --upgrade setuptools wheel twine

The preferred versions:
Copy link
Member

Choose a reason for hiding this comment

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

Can this be worded as something along the lines of the following instead?

The minimum required versions of the respective tools are:


- ``setuptools>=38.6.0``
Copy link
Member

Choose a reason for hiding this comment

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

I think we should add spaces around >=.

I find setuptools >= 38.6.0 more readable than setuptools>=38.6.0.

- ``wheel>=0.31.0``
- ``twine>=1.11.0``

It's recommended that you use ``twine`` to upload the project's distribution packages:

.. code-block:: bash

twine upload dist/*

Copy link
Member

Choose a reason for hiding this comment

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

minor nit: too many newlines



For example, see this :file:`setup.py` file,
which reads the contents of :file:`README.md` as ``long_description``
and identifies the markup as GitHub-flavored Markdown:
Expand Down