From d44999864280f9ecfe2e28c3ab75b11a704e43fd Mon Sep 17 00:00:00 2001 From: Iustin Pop Date: Sat, 23 Nov 2019 22:33:36 +0100 Subject: [PATCH] Switch README file to Markdown and expand it Let's get a bit more up with the times. --- MANIFEST.in | 5 ++-- Makefile | 9 ++++++- README.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.rst | 41 -------------------------------- doc/conf.py | 7 +++++- doc/index.rst | 5 ++-- doc/news.rst | 1 - 7 files changed, 86 insertions(+), 48 deletions(-) create mode 100644 README.md delete mode 100644 README.rst delete mode 120000 doc/news.rst diff --git a/MANIFEST.in b/MANIFEST.in index 6c709af..e59fd38 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,9 +1,10 @@ include COPYING include NEWS -include README.rst +include README.md include Makefile include doc/conf.py -include doc/*.rst +include doc/index.rst +include doc/module.rst include setup.cfg include test/test_xattr.py include test/__init__.py diff --git a/Makefile b/Makefile index 7515457..bafcd44 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,7 @@ DOCTREES = $(DOCDIR)/doctrees ALLSPHINXOPTS = -d $(DOCTREES) $(SPHINXOPTS) $(DOCDIR) MODNAME = xattr.so -RSTFILES = doc/index.rst doc/module.rst NEWS README.rst doc/conf.py +RSTFILES = doc/index.rst doc/module.rst doc/news.rst doc/readme.md doc/conf.py PYVERS = 2.4 2.5 2.6 2.7 3.0 3.1 3.2 3.3 3.4 3.5 3.6 3.7 REPS = 5 @@ -22,6 +22,12 @@ $(DOCHTML)/index.html: $(MODNAME) $(RSTFILES) doc: $(DOCHTML)/index.html +doc/readme.md: README.md + ln -s ../README.md doc/readme.md + +doc/news.rst: NEWS + ln -s ../NEWS doc/news.rst + dist: fakeroot $(PYTHON) ./setup.py sdist @@ -66,6 +72,7 @@ coverage: clean: rm -rf $(DOCHTML) $(DOCTREES) + rm -f doc/readme.md doc/news.rst rm -f $(MODNAME) rm -f *.so rm -rf build diff --git a/README.md b/README.md new file mode 100644 index 0000000..e63ac8f --- /dev/null +++ b/README.md @@ -0,0 +1,66 @@ +# pyxattr + +This is the pyxattr module, a Python extension module which gives access +to the extended attributes for filesystem objects available in some +operating systems. + +[![Travis](https://img.shields.io/travis/iustin/pyxattr)](https://travis-ci.org/iustin/pyxattr) +[![Coveralls github](https://img.shields.io/coveralls/github/iustin/pyxattr)](https://coveralls.io/github/iustin/pyxattr) +[![Read the Docs](https://img.shields.io/readthedocs/pyxattr)](http://pyxattr.readthedocs.io/en/latest/?badge=latest) +[![GitHub issues](https://img.shields.io/github/issues/iustin/pyxattr)](https://github.com/iustin/pyxattr/issues) +![GitHub tag (latest by date)](https://img.shields.io/github/v/tag/iustin/pyxattr) +[![GitHub release (latest by date)](https://img.shields.io/github/v/release/iustin/pyxattr)](https://github.com/iustin/pyxattr/releases) +[![PyPI](https://img.shields.io/pypi/v/pyxattr)](https://pypi.org/project/pyxattr/) +![Debian package](https://img.shields.io/debian/v/python-pyxattr) +![Ubuntu package](https://img.shields.io/ubuntu/v/python-pyxattr) +![GitHub Release Date](https://img.shields.io/github/release-date/iustin/pyxattr) +![GitHub commits since latest release](https://img.shields.io/github/commits-since/iustin/pyxattr/latest) +![GitHub last commit](https://img.shields.io/github/last-commit/iustin/pyxattr) + +Downloads: go to . The source +repository is either at or at +. + +## Requirements + +pyxattr has been written and tested on Linux, kernel v2.4 or later, +with XFS and ext2/ext3/ext3 file systems. If any other platform +implements the same behaviour, pyxattr could be used. + +You need to have the setuptools tool installed in order to build and +install the module, and for building the documentation you need to +have Sphinx installed. + +Alternatively, you can install directly from pip: + + $ pip install pyxattr + +Or from your distribution, e.g. in Debian: + + $ sudo install python3-pyxattr + +## Basic example + + >>> import xattr + >>> xattr.listxattr("file.txt") + ['user.mime_type'] + >>> xattr.getxattr("file.txt", "user.mime_type") + 'text/plain' + >>> xattr.setxattr("file.txt", "user.comment", "Simple text file") + >>> xattr.listxattr("file.txt") + ['user.mime_type', 'user.comment'] + >>> xattr.removexattr ("file.txt", "user.comment") + +## License + +pyxattr is Copyright 2002-2008, 2012-2015 Iustin Pop. + +pyxattr is free software; you can redistribute it and/or modify it under the +terms of the GNU Lesser General Public License as published by the Free +Software Foundation; either version 2.1 of the License, or (at your option) any +later version. See the COPYING file for the full license terms. + +Note that previous versions had different licenses: version 0.3 was licensed +under LGPL version 3 (which, I realized later, is not compatible with GPLv2, +hence the change to LGPL 2.1), and even older versions were licensed under GPL +v2 or later. diff --git a/README.rst b/README.rst deleted file mode 100644 index 033d597..0000000 --- a/README.rst +++ /dev/null @@ -1,41 +0,0 @@ -pyxattr -======= - -This is the pyxattr module, a Python extension module which gives access -to the extended attributes for filesystem objects available in some -operating systems. - -Downloads: go to https://pyxattr.k1024.org/downloads/. Latest -version is 0.6.1. The source repository is either at -http://git.k1024.org/pyxattr.git or at -https://github.com/iustin/pyxattr. - -Requirements ------------- - -pyxattr has been written and tested on Linux, kernel v2.4 or later, with -XFS filesystems; ext2/ext3 should work also. If any other platform -implements the same behavior, pyxattr could be used. - -You need to have the setuptools tool installed in order to build and -install the module. - -License -------- - -pyxattr is Copyright 2002-2008, 2012-2015 Iustin Pop. - -pyxattr is free software; you can redistribute it and/or modify it under the -terms of the GNU Lesser General Public License as published by the Free -Software Foundation; either version 2.1 of the License, or (at your option) any -later version. See the COPYING file for the full license terms. - -Note that previous versions had different licenses: version 0.3 was licensed -under LGPL version 3 (which, I realized later, is not compatible with GPLv2, -hence the change to LGPL 2.1), and even older versions were licensed under GPL -v2 or later. - -.. Local Variables: -.. mode: rst -.. fill-column: 72 -.. End: diff --git a/doc/conf.py b/doc/conf.py index a2ac56a..374cd19 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -31,7 +31,7 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo'] templates_path = ['_templates'] # The suffix of source filenames. -source_suffix = '.rst' +source_suffix = ['.rst', '.md'] # The encoding of source files. #source_encoding = 'utf-8-sig' @@ -90,6 +90,11 @@ pygments_style = 'sphinx' keep_warnings = True +# Note: this is still needed in Sphinx 1.8 with recommonmark 0.4.0 +# (https://github.com/readthedocs/recommonmark/issues/119): +source_parsers = { + '.md': 'recommonmark.parser.CommonMarkParser', +} # -- Options for HTML output --------------------------------------------------- diff --git a/doc/index.rst b/doc/index.rst index 6032182..a918c2e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -2,8 +2,8 @@ Welcome to pyxattr's documentation! ====================================== -.. include:: ../README.rst - :start-line: 2 +See the :doc:`README ` for start, or the detailed :doc:`module +` information. Contents -------- @@ -11,6 +11,7 @@ Contents .. toctree:: :maxdepth: 2 + readme.md module.rst news.rst diff --git a/doc/news.rst b/doc/news.rst deleted file mode 120000 index 0fae0f8..0000000 --- a/doc/news.rst +++ /dev/null @@ -1 +0,0 @@ -../NEWS \ No newline at end of file -- 2.39.5