diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/code_style.rst | 37 | ||||
| -rw-r--r-- | docs/media_repository.rst | 25 |
2 files changed, 59 insertions, 3 deletions
diff --git a/docs/code_style.rst b/docs/code_style.rst index d7e2d5e69e..dc40a7ab7b 100644 --- a/docs/code_style.rst +++ b/docs/code_style.rst @@ -1,10 +1,14 @@ Basically, PEP8 -- Max line width: 80 chars. +- NEVER tabs. 4 spaces to indent. +- Max line width: 79 chars (with flexibility to overflow by a "few chars" if + the overflowing content is not semantically significant and avoids an + explosion of vertical whitespace). - Use camel case for class and type names - Use underscores for functions and variables. - Use double quotes. -- Use parentheses instead of '\' for line continuation where ever possible (which is pretty much everywhere) +- Use parentheses instead of '\\' for line continuation where ever possible + (which is pretty much everywhere) - There should be max a single new line between: - statements - functions in a class @@ -14,5 +18,32 @@ Basically, PEP8 - a single space after a comma - a single space before and after for '=' when used as assignment - no spaces before and after for '=' for default values and keyword arguments. +- Indenting must follow PEP8; either hanging indent or multiline-visual indent + depending on the size and shape of the arguments and what makes more sense to + the author. In other words, both this:: -Comments should follow the google code style. This is so that we can generate documentation with sphinx (http://sphinxcontrib-napoleon.readthedocs.org/en/latest/) + print("I am a fish %s" % "moo") + + and this:: + + print("I am a fish %s" % + "moo") + + and this:: + + print( + "I am a fish %s" % + "moo" + ) + + ...are valid, although given each one takes up 2x more vertical space than + the previous, it's up to the author's discretion as to which layout makes most + sense for their function invocation. (e.g. if they want to add comments + per-argument, or put expressions in the arguments, or group related arguments + together, or want to deliberately extend or preserve vertical/horizontal + space) + +Comments should follow the google code style. This is so that we can generate +documentation with sphinx (http://sphinxcontrib-napoleon.readthedocs.org/en/latest/) + +Code should pass pep8 --max-line-length=100 without any warnings. diff --git a/docs/media_repository.rst b/docs/media_repository.rst new file mode 100644 index 0000000000..e4a6974041 --- /dev/null +++ b/docs/media_repository.rst @@ -0,0 +1,25 @@ +Media Repository +================ + +The media repository is where attachments and avatar photos are stored. +It stores attachment content and thumbnails for media uploaded by local users. +It caches attachment content and thumbnails for media uploaded by remote users. + +Storage +------- + +Each item of media is assigned a ``media_id`` when it is uploaded. +The ``media_id`` is a randomly chosen, URL safe 24 character string. +Metadata such as the MIME type, upload time and length are stored in the +sqlite3 database indexed by ``media_id``. +Content is stored on the filesystem under a ``"local_content"`` directory. +Thumbnails are stored under a ``"local_thumbnails"`` directory. +The item with ``media_id`` ``"aabbccccccccdddddddddddd"`` is stored under +``"local_content/aa/bb/ccccccccdddddddddddd"``. Its thumbnail with width +``128`` and height ``96`` and type ``"image/jpeg"`` is stored under +``"local_thumbnails/aa/bb/ccccccccdddddddddddd/128-96-image-jpeg"`` +Remote content is cached under ``"remote_content"`` directory. Each item of +remote content is assigned a local "``filesystem_id``" to ensure that the +directory structure ``"remote_content/server_name/aa/bb/ccccccccdddddddddddd"`` +is appropriate. Thumbnails for remote content are stored under +``"remote_thumbnails/server_name/..."`` |