PyPi mô tả markdown không hoạt động

Question

Tôi đã tải lên một gói để PyPi sử dụng:

python setup.py register -r pypi 
python setup.py sdist upload -r pypi 

Tôi đang cố gắng để thay đổi decsription, tôi đã viết (xin vui lòng không chỉnh sửa định dạng của đoạn mã sau , tôi đã làm cho nó trong mục đích để chứng minh vấn đề của tôi):

**nose-docstring-plugin** 

This plugin enables you to modify docstring of tests based on their attributes, for example: 
```python 
@attr(section='MySection', type='functional+', module='MyModule', id=1) 
def test_function(self): 
    """ 
    This is the original docstring 
    """ 
    pass 
``` 

Tuy nhiên, các văn bản xuất hiện như nó có, mà không định dạng Markdown. Tôi đang làm gì sai?

Answer 1

PyPI hiện không hỗ trợ Đánh dấu, vì vậy README của bạn sẽ không được hiển thị thành HTML.

Nếu bạn muốn một README được hiển thị, hãy gắn với reStructuredText; Sphinx introduction to reStructuredText là điểm khởi đầu tốt.

Bạn có thể muốn cài đặt docutils package để bạn có thể kiểm tra tài liệu của mình cục bộ; bạn muốn chạy tập lệnh đính kèm rst2html.py trên README để xem lỗi nào được tạo ra, nếu có. Mẫu cụ thể của bạn có quá nhiều lỗi:

$ bin/rst2html.py test.rst > /tmp/test.html 
test.rst:7: (ERROR/3) Unexpected indentation. 
test.rst:3: (WARNING/2) Inline literal start-string without end-string. 
test.rst:3: (WARNING/2) Inline interpreted text or phrase reference start-string without end-string. 
test.rst:11: (WARNING/2) Block quote ends without a blank line; unexpected unindent. 
test.rst:11: (WARNING/2) Inline literal start-string without end-string. 
test.rst:11: (WARNING/2) Inline interpreted text or phrase reference start-string without end-string. 

Khối mã của bạn đang sử dụng tiện ích mở rộng Markdown của Github, hoàn toàn sai đối với reStructuredText. Bạn có thể sử dụng một khối mã còn lại (có lẽ, nếu phiên bản PyPI của docutils là mới đủ):

.. code-block:: python 

    @attr(section='MySection', type='functional+', module='MyModule', id=1) 
    def test_function(self): 
     """ 
     This is the original docstring 
     """ 
     pass 

Để kiểm tra điều này tại địa phương bạn sẽ cần phải cài đặt Pygments là tốt.

Có một số feature request with pull request để thêm hỗ trợ cho Đánh dấu, nếu bạn quan tâm.

Answer 2

Như @Martijn Pieters đã nêu, PyPi không hỗ trợ Đánh dấu. Tôi không chắc chắn nơi tôi đã học được thủ thuật sau đây, nhưng bạn có thể sử dụng Pandoc và PyPandoc để chuyển đổi các tệp Markdown của bạn thành Cấu trúc lại trước khi tải lên PyPi. Để thực hiện điều này, thêm dòng sau vào setup.py tập tin của bạn:

try: 
    import pypandoc 
    long_description = pypandoc.convert('README.md', 'rst') 
except(IOError, ImportError): 
    long_description = open('README.md').read() 

setup(
    name='blah', 
    version=find_version('blah.py'), 
    description='Short description', 
    long_description=long_description, 
) 

Để cài đặt Pandoc trên OS X, tôi đã sử dụng Homebrew:

brew install pandoc 

Để cài đặt PyPandoc, tôi sử dụng pip:

pip install pypandoc 

Answer 3

Tôi gặp sự cố với \r các ký tự gây ra sự cố phân tích cú pháp mà chỉ có dòng đầu tiên của thứ e README xuất hiện trong pypi. Đoạn code dưới đây sửa chữa vấn đề này, nó xuất phát từ kho pypandoc mô-đun:

try: 
    long_description = pypandoc.convert('README.md', 'rst') 
    long_description = long_description.replace("\r","") # Do not forget this line 
except OSError: 
    print("Pandoc not found. Long_description conversion failure.") 
    import io 
    # pandoc is not installed, fallback to using raw contents 
    with io.open('README.md', encoding="utf-8") as f: 
     long_description = f.read() 

Bằng cách này long_description chứa một phiên bản làm vệ sinh của Readme của bạn và bạn có thể vượt qua nó để setup() chức năng trong setup.py kịch bản của bạn.

Answer 4

PyPI hỗ trợ rst và không đánh dấu như được đề cập trên các câu trả lời khác. Nhưng bạn không cần pypandoc perse, chỉ cần pandoc là tốt. Bạn có thể tạo tệp đầu tiên cục bộ trước và sau đó chạy thiết lập.py để tải lên gói.

upload.sh:

#!/bin/bash 
pandoc --from=markdown --to=rst --output=README README.md 
python setup.py sdist upload 

Các tập tin được tạo ra có tên README sẽ tự động được công nhận. Hãy chắc chắn thêm nó vào .gitignore của bạn! setup.py không phải làm bất cứ điều gì đặc biệt.

setup.py:

from distutils.core import setup 

setup(
    name='mypackage', 
    packages=['mypackage'], # this must be the same as the name above 
    version='0.2.8', 
    description='short', 
    author='Chiel ten Brinke', 
    author_email='<email>', 
    url='<github url>', # use the URL to the github repo 
    keywords=[], # arbitrary keywords 
    classifiers=[], 
) 

Sau đó chỉ cần chạy bash upload.sh để tải lên các công cụ để PyPI.

Answer 5

Có một gói pip tốt mà làm việc cho tôi

https://pypi.python.org/pypi/restructuredtext_lint/

Tôi đang sử dụng nó vào thiết lập của tôi bây giờ:

https://github.com/pablodav/burp_server_reports/blob/master/setup.py

def check_readme(file='README.rst'): 
""" 
Checks readme rst file, to ensure it will upload to pypi and be formatted correctly. 
:param file: 
:return: 
""" 
errors = rst_lint.lint_file(file) 
if errors: 
    msg = 'There are errors in {}, errors \n {}'.format(file, errors[0].message) 
    raise SystemExit(msg) 
else: 
    msg = 'No errors in {}'.format(file) 
print(msg) 

Ngoài ra tôi đã tạo ra một lib để có thể sử dụng trong py.test sau

https://github.com/pablodav/burp_server_reports/blob/master/burp_reports/lib/check_readme.py