From 9ca0f2f0ffb8bad507bd340005ff41e2aa01114e Mon Sep 17 00:00:00 2001 From: Iustin Pop Date: Sun, 13 May 2012 04:14:32 +0200 Subject: [PATCH] Reorganise documentation Lots of changes so that all docs are buildable by Sphinx. --- .gitignore | 3 +- Makefile | 4 +- NEWS | 26 ++++++---- PLATFORMS | 30 ------------ PORTING | 23 --------- README.md | 2 +- doc/conf.py | 7 ++- IMPLEMENTATION => doc/implementation.rst | 60 ++++++++++++++++++++++++ doc/index.rst | 12 ++--- doc/module.rst | 4 ++ doc/news.rst | 1 + 11 files changed, 97 insertions(+), 75 deletions(-) delete mode 100644 PLATFORMS delete mode 100644 PORTING rename IMPLEMENTATION => doc/implementation.rst (51%) create mode 100644 doc/module.rst create mode 120000 doc/news.rst diff --git a/.gitignore b/.gitignore index 0aabe9a..e108039 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,8 @@ /MANIFEST /build /dist -/html +/doc/doctrees +/doc/html /posix1e.html /posix1e.so /posix1e.txt diff --git a/Makefile b/Makefile index b159bc4..5824c93 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -SPHINXOPTS = +SPHINXOPTS = -W SPHINXBUILD = sphinx-build DOCDIR = doc DOCHTML = $(DOCDIR)/html @@ -13,7 +13,7 @@ $(MODNAME): acl.c ./setup.py build_ext --inplace doc: $(MODNAME) - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(DOCHTML) + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DOCHTML) test: for ver in 2.4 2.5 2.6 3.0 3.1; do \ diff --git a/NEWS b/NEWS index b14b96c..baa6468 100644 --- a/NEWS +++ b/NEWS @@ -1,19 +1,22 @@ +News +==== + Version 0.5 -=========== +----------- Added support for Python 3.x and improved support for Unicode filenames. Version 0.4 -=========== +----------- License -------- +~~~~~~~ Starting with this version, pylibacl is licensed under LGPL 2.1, Febryary 1999 or any later versions (see README and COPYING). Linux support -------------- +~~~~~~~~~~~~~ A few more Linux-specific functions: @@ -25,7 +28,7 @@ A few more Linux-specific functions: has an extended ACL FreeBSD support ---------------- +~~~~~~~~~~~~~~~ FreeBSD 7.x will have almost all the acl manipulation functions that Linux has, with the exception of __getstate__/__setstate__. As a @@ -33,7 +36,7 @@ workaround, use the str() and ACL(text=...) methods to pass around textual representations. Interface ---------- +~~~~~~~~~ At module level there are now a few constants exported for easy-checking at runtime what features have been compiled in: @@ -54,16 +57,16 @@ at runtime what features have been compiled in: equiv_mode() method Internals ---------- +~~~~~~~~~ Many functions have now unittests, which is a good thing. Version 0.3 -=========== +----------- Linux support -------------- +~~~~~~~~~~~~~ Under Linux, implement more functions from libacl: @@ -71,3 +74,8 @@ Under Linux, implement more functions from libacl: - add ACL().to_any_text, implementing acl_to_any_text - add ACL comparison, using acl_cmp - add ACL().check, which is a more descriptive function than validate + +.. Local Variables: +.. mode: rst +.. fill-column: 72 +.. End: diff --git a/PLATFORMS b/PLATFORMS deleted file mode 100644 index 6c05d1d..0000000 --- a/PLATFORMS +++ /dev/null @@ -1,30 +0,0 @@ -Current supported platforms -=========================== - -Linux ------ - -It needs kernel 2.4 or higher and the libacl library installed (with -development headers, if installing from rpm). This library is available -on all modern distributions. - -The level of compliance is level 2 (see IMPLEMENTATION), plus some extra -functions; and as my development is done on Linux, I try to implement -these extensions when it makes sense. - - -FreeBSD -------- - -The current tested version is 7.0. FreeBSD supports all the standards -functions, but 7.0-RELEASE seems to have some issues regarding the -acl_valid() function when the qualifier of an ACL_USER or ACL_GROUP -entry is the same as the current uid. By my interpretation, this should -be a valid ACL, but FreeBSD declares the ACL invalid. As such, some -unittests fail on FreeBSD. - - -Other platforms ---------------- - -For any other platforms, volunteers are welcome - read the PORTING file. diff --git a/PORTING b/PORTING deleted file mode 100644 index a2419ff..0000000 --- a/PORTING +++ /dev/null @@ -1,23 +0,0 @@ -Porting to other platforms --------------------------- - -First, determine if your OS supports the full 28 functions of the -POSIX.1e draft (if so, define HAVE_LEVEL2) or only the first 11 -functions (most common case, meaning only HAVE_LEVEL1). - -If your OS supports only LEVEL1, modift setup.py as appropriately; -unfortunately, the functionality of the module is quite low. - -If your OS supports LEVEL2, there is a function which you must define: -testing if an acl_permset_t contains a given permission. For example, -under Linux, the acl library defines: - - int acl_get_perm(acl_permset_t permset_d, acl_perm_t perm); - -under FreeBSD, the library defines ``acl_get_perm_np`` with a similar -syntax. So just see how this is implemented in your platform and either -define a simple macro or a full function with the syntax: - - static int get_perm(acl_permset_t permset_d, acl_perm_t perm); - -which must return 1 if the permset contains perm and 0 otherwise. diff --git a/README.md b/README.md index 7bba91e..3d7abf5 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ A few internal details are in the file IMPLEMENTATION. License ------- -pylibacl is Copyright (C) 2002-2009 Iustin Pop. +pylibacl is Copyright (C) 2002-2009, 2012 Iustin Pop. pylibacl 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 diff --git a/doc/conf.py b/doc/conf.py index 1910647..3b2d215 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -122,7 +122,8 @@ html_theme = 'default' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +#html_static_path = ['_static'] +html_static_path = [] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. @@ -141,9 +142,11 @@ html_static_path = ['_static'] # If false, no module index is generated. #html_domain_indices = True +html_domain_indices = False # If false, no index is generated. #html_use_index = True +html_use_index = False # If true, the index is split into individual pages for each letter. #html_split_index = False @@ -243,3 +246,5 @@ texinfo_documents = [ # How to display URL addresses: 'footnote', 'no', or 'inline'. #texinfo_show_urls = 'footnote' + +autodoc_member_order = 'alphabetical' diff --git a/IMPLEMENTATION b/doc/implementation.rst similarity index 51% rename from IMPLEMENTATION rename to doc/implementation.rst index e065241..54977e4 100644 --- a/IMPLEMENTATION +++ b/doc/implementation.rst @@ -1,3 +1,6 @@ +Implementation details +====================== + Functionality level ------------------- @@ -47,3 +50,60 @@ The POSIX draft has the following stuff (correct me if I'm wrong): - the acl_permset_t can contain acl_perm_t value (ACL_READ, ACL_WRITE, ACL_EXECUTE, ACL_ADD, ACL_DELETE, ...) - functions to manipulate all these, and functions to manipulate files + +Currently supported platforms +----------------------------- + +For any other platforms, volunteers are welcome. + +Linux +~~~~~ + +It needs kernel 2.4 or higher and the libacl library installed (with +development headers, if installing from rpm). This library is available +on all modern distributions. + +The level of compliance is level 2 (see IMPLEMENTATION), plus some extra +functions; and as my development is done on Linux, I try to implement +these extensions when it makes sense. + + +FreeBSD +~~~~~~~ + +The current tested version is 7.0. FreeBSD supports all the standards +functions, but 7.0-RELEASE seems to have some issues regarding the +acl_valid() function when the qualifier of an ACL_USER or ACL_GROUP +entry is the same as the current uid. By my interpretation, this should +be a valid ACL, but FreeBSD declares the ACL invalid. As such, some +unittests fail on FreeBSD. + +Porting to other platforms +-------------------------- + +First, determine if your OS supports the full 28 functions of the +POSIX.1e draft (if so, define HAVE_LEVEL2) or only the first 11 +functions (most common case, meaning only HAVE_LEVEL1). + +If your OS supports only LEVEL1, modify ``setup.py`` as appropriately; +unfortunately, the functionality of the module is quite low. + +If your OS supports LEVEL2, there is a function which you must define: +testing if an acl_permset_t contains a given permission. For example, +under Linux, the acl library defines:: + + int acl_get_perm(acl_permset_t permset_d, acl_perm_t perm); + +under FreeBSD, the library defines ``acl_get_perm_np`` with a similar +syntax. So just see how this is implemented in your platform and either +define a simple macro or a full function with the syntax:: + + static int get_perm(acl_permset_t permset_d, acl_perm_t perm); + +which must return 1 if the permset contains perm and 0 otherwise. + + +.. Local Variables: +.. mode: rst +.. fill-column: 72 +.. End: diff --git a/doc/index.rst b/doc/index.rst index 509acbe..63eb4ff 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -6,12 +6,8 @@ Contents: .. toctree:: :maxdepth: 2 -.. automodule:: posix1e - :members: + module.rst + implementation.rst + news.rst -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +Also see the :ref:`search`. diff --git a/doc/module.rst b/doc/module.rst new file mode 100644 index 0000000..b5fa851 --- /dev/null +++ b/doc/module.rst @@ -0,0 +1,4 @@ +.. automodule:: posix1e + :members: + :undoc-members: + diff --git a/doc/news.rst b/doc/news.rst new file mode 120000 index 0000000..0fae0f8 --- /dev/null +++ b/doc/news.rst @@ -0,0 +1 @@ +../NEWS \ No newline at end of file -- 2.39.5