From d67688bdce80e578bbf9313f5ec91102f47ffd92 Mon Sep 17 00:00:00 2001 From: Iustin Pop Date: Sat, 28 Jun 2008 15:41:57 +0200 Subject: [PATCH] Docstring updates for epydoc compatibility By just changing a few docstrings, epydoc can generate much better documentation - the docstrings were half-compatible already with the epytext format. Also the makefile and manifest were updated not to include and build the default pydoc documentation. --- .gitignore | 1 + MANIFEST.in | 10 +++--- Makefile | 17 +++++----- acl.c | 95 +++++++++++++++++++++++++++++++---------------------- 4 files changed, 68 insertions(+), 55 deletions(-) diff --git a/.gitignore b/.gitignore index 3e9bf92..0aabe9a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ /MANIFEST /build /dist +/html /posix1e.html /posix1e.so /posix1e.txt diff --git a/MANIFEST.in b/MANIFEST.in index fc23179..cfa3c0a 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,9 +1,7 @@ -include README -include PLATFORMS include IMPLEMENTATION -include acl.c include MANIFEST -include posix1e.html -include posix1e.txt -include setup.cfg include NEWS +include PLATFORMS +include README +include acl.c +include setup.cfg diff --git a/Makefile b/Makefile index e1a34e5..1e1537b 100644 --- a/Makefile +++ b/Makefile @@ -1,18 +1,17 @@ .PHONY: doc log test -doc: posix1e.txt posix1e.html - -build/lib.linux-x86_64-2.4/posix1e.so: acl.c - ./setup.py build +all: doc test posix1e.so: acl.c ./setup.py build_ext --inplace -posix1e.txt: posix1e.so - pydoc posix1e > posix1e.txt - -posix1e.html: posix1e.so - pydoc -w posix1e +doc: posix1e.so + epydoc -q -o html --name pylibacl \ + --url http://pylibacl.sourceforge.net/ \ + --show-frames \ + --docformat epytext \ + --no-sourcecode \ + posix1e test: python2.4 ./setup.py test diff --git a/acl.c b/acl.c index b27ab2b..9fe0b5e 100644 --- a/acl.c +++ b/acl.c @@ -180,18 +180,18 @@ static char __to_any_text_doc__[] = " - separator: a single character (defaults to '\\n'); this will be\n" " user to separate the entries in the ACL\n" " - options: a bitwise combination of:\n" - " TEXT_ABBREVIATE: use 'u' instead of 'user', 'g' instead of \n" + " - TEXT_ABBREVIATE: use 'u' instead of 'user', 'g' instead of \n" " 'group', etc.\n" - " TEXT_NUMERIC_IDS: User and group IDs are included as decimal\n" - " numbers instead of names\n" - " TEXT_SOME_EFFECTIVE: Include comments denoting the effective\n" - " permissions when some are masked\n" - " TEXT_ALL_EFFECTIVE: Include comments after all ACL entries\n" - " affected by an ACL_MASK entry\n" - " TEXT_SMART_INDENT: Used in combination with the _EFFECTIVE\n" - " options, this will ensure that comments \n" - " are alligned to the fourth tab position\n" - " (assuming one tab equal eight spaces\n" + " - TEXT_NUMERIC_IDS: User and group IDs are included as decimal\n" + " numbers instead of names\n" + " - TEXT_SOME_EFFECTIVE: Include comments denoting the effective\n" + " permissions when some are masked\n" + " - TEXT_ALL_EFFECTIVE: Include comments after all ACL entries\n" + " affected by an ACL_MASK entry\n" + " - TEXT_SMART_INDENT: Used in combination with the _EFFECTIVE\n" + " options, this will ensure that comments \n" + " are alligned to the fourth tab position\n" + " (assuming one tab equals eight spaces)\n" ; /* Converts the acl to a custom text format */ @@ -493,9 +493,9 @@ static char __ACL_delete_entry_doc__[] = "\n" "Note: Only with level 2\n" "Parameters:\n" - " - the Entry object which should be deleted; note that after\n" - " this function is called, that object is unusable any longer\n" - " and should be deleted\n" + " - the Entry object which should be deleted; note that after\n" + " this function is called, that object is unusable any longer\n" + " and should be deleted\n" ; /* Deletes an entry from the ACL */ @@ -972,10 +972,12 @@ static char __Permset_add_doc__[] = "the argument perm to the permission set. An attempt \n" "to add a permission that is already contained in the \n" "permission set is not considered an error.\n" - "Parameters:\n" - " - perm a permission (ACL_WRITE, ACL_READ, ACL_EXECUTE, ...\n" - "Return value:\n" - " None\n" + "\n" + "Parameters:\n\n" + " - perm: a permission (ACL_WRITE, ACL_READ, ACL_EXECUTE, ...)\n" + "\n" + "Return value: None\n" + "\n" "Can raise: IOError\n" ; @@ -1001,10 +1003,10 @@ static char __Permset_delete_doc__[] = "the argument perm from the permission set. An attempt \n" "to delete a permission that is not contained in the \n" "permission set is not considered an error.\n" - "Parameters:\n" - " - perm a permission (ACL_WRITE, ACL_READ, ACL_EXECUTE, ...\n" - "Return value:\n" - " None\n" + "Parameters:\n\n" + " - perm a permission (ACL_WRITE, ACL_READ, ACL_EXECUTE, ...)\n" + "Return value: None\n" + "\n" "Can raise: IOError\n" ; @@ -1028,10 +1030,10 @@ static char __Permset_test_doc__[] = "\n" "The test() function tests if the permission contained in \n" "the argument perm exits the permission set.\n" - "Parameters:\n" - " - perm a permission (ACL_WRITE, ACL_READ, ACL_EXECUTE, ...\n" - "Return value:\n" - " Bool\n" + "Parameters:\n\n" + " - perm a permission (ACL_WRITE, ACL_READ, ACL_EXECUTE, ...)\n" + "Return value: Boolean\n" + "\n" "Can raise: IOError\n" ; @@ -1061,8 +1063,7 @@ static PyObject* Permset_test(PyObject* obj, PyObject* args) { static char __ACL_Type_doc__[] = "Type which represents a POSIX ACL\n" "\n" - "Parameters:\n" - " Only one keword parameter should be provided:\n" + "Parameters (only one keword parameter should be provided):\n" " - file=\"...\", meaning create ACL representing\n" " the access ACL of that file\n" " - filedef=\"...\", meaning create ACL representing\n" @@ -1076,9 +1077,10 @@ static char __ACL_Type_doc__[] = " - mode=, meaning create an ACL from a numeric mode\n" " (e.g. mode=0644) (this is valid only when the C library\n" " provides the acl_from_mode call)\n" + "\n" "If no parameters are passed, create an empty ACL; this\n" "makes sense only when your OS supports ACL modification\n" - " (i.e. it implements full POSIX.1e support)\n" + "(i.e. it implements full POSIX.1e support)\n" ; /* ACL type methods */ @@ -1211,10 +1213,13 @@ static char __Entry_Type_doc__[] = "\n" "The type exists only if the OS has full support for POSIX.1e\n" "Can be created either by:\n" - " e = posix1e.Entry(myACL) # this creates a new entry in the ACL\n" + "\n" + " >>> e = posix1e.Entry(myACL) # this creates a new entry in the ACL\n" + " >>> e = myACL.append() # another way for doing the same thing\n" + "\n" "or by:\n" - " for entry in myACL:\n" - " print entry\n" + " >>> for entry in myACL:\n" + " ... print entry\n" "\n" "Note that the Entry keeps a reference to its ACL, so even if \n" "you delete the ACL, it won't be cleaned up and will continue to \n" @@ -1314,10 +1319,11 @@ static char __Permset_Type_doc__[] = "Type which represents the permission set in an ACL entry\n" "\n" "The type exists only if the OS has full support for POSIX.1e\n" - "Can be created either by:\n" - " perms = myEntry.permset\n" - "or by:\n" - " perms = posix1e.Permset(myEntry)\n" + "Can be retrieved either by:\n\n" + ">>> perms = myEntry.permset\n" + "\n" + "or by:\n\n" + ">>> perms = posix1e.Permset(myEntry)\n" "\n" "Note that the Permset keeps a reference to its Entry, so even if \n" "you delete the entry, it won't be cleaned up and will continue to \n" @@ -1461,29 +1467,38 @@ static char __posix1e_doc__[] = " the ACL once it is created\n" "\n" "Also, in level 2, more types are available, corresponding\n" - "to acl_entry_t (Entry type), acl_permset_t (Permset type).\n" + "to acl_entry_t (the Entry type), acl_permset_t (the Permset type).\n" + "\n" + "The existence of level 2 support and other extensions can be\n" + "checked by the constants:\n" + " - HAS_ACL_ENTRY for level 2 and the Entry/Permset classes\n" + " - HAS_ACL_FROM_MODE for ACL(mode=...) usage\n" + " - HAS_ACL_CHECK for the ACL().check function\n" + " - HAS_EXTENDED_CHECK for the module-level has_extended function\n" + " - HAS_EQUIV_MODE for the ACL().equiv_mode method\n" "\n" "Example:\n" + "\n" ">>> import posix1e\n" ">>> acl1 = posix1e.ACL(file=\"file.txt\") \n" ">>> print acl1\n" "user::rw-\n" "group::rw-\n" "other::r--\n" - "\n" + ">>>\n" ">>> b = posix1e.ACL(text=\"u::rx,g::-,o::-\")\n" ">>> print b\n" "user::r-x\n" "group::---\n" "other::---\n" - "\n" + ">>>\n" ">>> b.applyto(\"file.txt\")\n" ">>> print posix1e.ACL(file=\"file.txt\")\n" "user::r-x\n" "group::---\n" "other::---\n" - "\n" ">>>\n" + "\n" ; void initposix1e(void) { -- 2.39.5