diff --git a/README b/README deleted file mode 100644 index 0cb454623212e0acef3d341711f2939233d9b2b7..0000000000000000000000000000000000000000 --- a/README +++ /dev/null @@ -1,83 +0,0 @@ -Djblets is a set of utility classes and functions for web applications -written using Django and Python. - -This is part of the Review Board project. To report a bug, please use the -Review Board bug tracker at http://www.reviewboard.org/bugs/ - - -Modules -======= - -auth ----- - -Flexible forms for registration processing and other useful forms. - - -datagrid --------- - -Customizable datagrids that represent paginated lists of database objects. -Users can customize the list of columns they list, reorder them, and sort -them. Datagrids take care of all the hard work behind the scenes. - - -feedview --------- - -Views and templates for providing a simple RSS reader. Handles caching the -feeds for quick access. - - -gravatars ---------- - -Template tags for inserting gravatars in a page. - - -log ---- - -Provides middleware that handles log initialization (with support for -reopening the log file after log rotation). If enabled in settings, -all pages can take a ?profiling=1 parameter that will log both code and SQL -profiling information to a separate log file. - - -markdown --------- - -Utility functions for processing Markdown trees, escaping/unescaping content, -and providing a more WYSIWYG level of rendered output for the given input. - - -siteconfig ----------- - -A powerful module for offering dynamic settings configuration in a web UI. -It wraps the Django settings module, stores serialized data in the database, -and loads it into the in-memory settings module. With siteconfig, webapps -can provide rich settings UIs without requiring that the adminsitrator -modify their settings.py. - - -testing -------- - -Helper classes for unit tests. Includes some small classes for testing basic -template tags, and classes for easily integrating Selenium unit tests. - - -util ----- - -A collection of various utility functions, template tags, and more. - - -webapi ------- - -A rich framework for implementing RESTful APIs in a web application. -Webapps can either provide a complete resource tree through the -WebAPIResource classes, or custom, simplified API handlers using -the basic WebAPIResponse classes. diff --git a/README.rst b/README.rst new file mode 100644 index 0000000000000000000000000000000000000000..4b4f1e8279d4bb3b3ce7ae018379883bf3bfabcd --- /dev/null +++ b/README.rst @@ -0,0 +1,256 @@ +Djblets +======= + +Djblets is a large collection of general and special-purpose building blocks +designed to help with the development of web applications written using +Django_ and Python. + +The following modules are available. These contain classes, functions, +template tags, templates, etc. that can be used by your own codebase. + +* djblets.auth_ - + Authentication-related utilities for registration, login rate limiting, and + other auth-related uses + +* djblets.avatars_ - + Avatar rendering with flexible backends (supporting Gravatars, custom URLs, + file uploads, or custom options) + +* djblets.cache_ - + Helpers for working with client-side and server-side caching needs + +* djblets.conditions_ - + User-defined condition rules under which actions should be performed + +* djblets.configforms_ - + Category-based, multi-form configuration pages + +* djblets.datagrid_ - + Customizable grids for displaying information, with custom columns + +* djblets.db_ - + Specialized fields, validation, and query operations for databases + +* djblets.extensions_ - + Extension framework, allowing third-party developers to extend your product + or service + +* djblets.features_ - + Feature flags for enabling/disabling functionality based on any criteria + +* djblets.feedview_ - + Inline RSS feed reader for news posts and other data + +* djblets.forms_ - + Specialized fields and widgets, enhanced form rendering, and + dictionary-backed form data + +* djblets.gravatars_ - + Low-level functions and template tags for injecting Gravatars_ into pages + +* djblets.integrations_ - + Framework for integrating with third-party services and offering unlimited + numbers of user-defined configurations + +* djblets.log_ - + Enhanced logging capabilities and log viewing + +* djblets.mail_ - + Enhanced Mail sending with DMARC checks and send-on-behalf-of-user + functionality + +* djblets.markdown_ - + Markdown rendering for pages and e-mails, with WYSIWYG editing/rendering + support + +* djblets.pipeline_ - + Pipeline_ compilers for ES6 JavaScript and optimized LessCSS support + +* djblets.privacy_ - + Privacy-by-design support, allowing consent to be requested and tracked + and personal information redacted + +* djblets.recaptcha_ - + Mixins and form widgets for reCAPTCHA_ integration + +* djblets.registries_ - + Base support for defining in-code registries, which tracks and allows lookup + of custom-registered objects + +* djblets.siteconfig_ - + In-database site configuration and settings, with Django settings mappings + +* djblets.template_ - + Loaders for intelligent template caching and utilities for working with + template caches and state + +* djblets.testing_ - + Utilities for enhancing unit tests and defining smarter test runners + +* djblets.urls_ - + Flexible root-level URL handlers, dynamic URL patterns that can be changed + at runtime, and more + +* djblets.util_ - + An assortment of misc. utility functions and template tags + +* djblets.views_ - + Class-based View mixins for controlling caching and more complex dispatch + behavior + +* djblets.webapi_ - + Foundation for building fully-featured, consisent, maintainable REST APIs + +We built and maintain Djblets as part of the `Review Board`_ code review +product and Splat_ bug tracker at Beanbag_. + +See the documentation_ for guides and code references for working with +Djblets. + + +.. _Beanbag: https://www.beanbaginc.com/ +.. _Django: https://www.djangoproject.com/ +.. _GDPR: https://www.eugdpr.org/ +.. _Gravatars: https://gravatars.com/ +.. _Pipeline: http://django-pipeline.readthedocs.io/en/latest/ +.. _reCAPTCHA: https://www.google.com/recaptcha/ +.. _Review Board: https://www.reviewboard.org/ +.. _Splat: https://www.hellosplat.com/ +.. _documentation: https://www.reviewboard.org/docs/djblets/latest/ + +.. _djblets.auth: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-auth +.. _djblets.avatars: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-avatars +.. _djblets.cache: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-cache +.. _djblets.conditions: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-conditions +.. _djblets.configforms: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-configforms +.. _djblets.datagrid: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-datagrid +.. _djblets.db: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-db +.. _djblets.extensions: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-extensions +.. _djblets.features: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-features +.. _djblets.feedview: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-feedview +.. _djblets.forms: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-forms +.. _djblets.gravatars: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-gravatars +.. _djblets.integrations: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-integrations +.. _djblets.log: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-log +.. _djblets.mail: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-mail +.. _djblets.markdown: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-markdown +.. _djblets.pipeline: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-pipeline +.. _djblets.privacy: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-privacy +.. _djblets.recaptcha: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-recaptcha +.. _djblets.registries: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-registries +.. _djblets.siteconfig: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-siteconfig +.. _djblets.template: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-template +.. _djblets.testing: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-testing +.. _djblets.urls: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-urls +.. _djblets.util: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-util +.. _djblets.views: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-views +.. _djblets.webapi: + https://www.reviewboard.org/docs/djblets/latest/coderef/#coderef-djblets-webapi + + +Compatibility +============= + +Djblets 0.9 (release-0.9.x_) supports Python 2.6 and 2.7, and Django 1.6. + +Djblets 1.0 (release-1.0.x_) supports Python 2.7 and Django 1.6. + +Djblets 2.0 (release-2.0.x_) supports Python 2.7, 3.5, and 3.6, and Django +1.6, 1.8, 1.0. 1,0. and 1.11. + +See the `release notes`_ for information on the latest public releases. + + +.. _release-0.9.x: https://github.com/djblets/djblets/tree/release-0.9.x +.. _release-1.0.x: https://github.com/djblets/djblets/tree/release-1.0.x +.. _release-2.0.x: https://github.com/djblets/djblets/tree/release-2.0.x +.. _release notes: https://www.reviewboard.org/docs/releasenotes/djblets/ + + +Installing Djblets +================== + +We provide source builds, Wheels, and Eggs for Djblets. We recommend you use +Wheels unless you have a reason to use Eggs or source builds. + +To install Wheels via pip:: + + $ pip install Djblets + +To install Eggs via easy_install:: + + $ easy_install Djblets + + +Getting Support +=============== + +We can help you with Djblets-related development over on our `Review Board +development list`_. + + +.. _Review Board development list: + https://http://groups.google.com/group/reviewboard-dev + + +Reporting Bugs +============== + +Hit a bug? Let us know by +`filing a bug report `_. + +You can also look through the +`existing bug reports `_ to see if anyone +else has already filed the bug. + + +Contributing +============ + +Are you a developer? Do you want to integrate Djblets into your project and +contribute back? Great! Let's help get you started. + +First off, we have a few handy guides: + +* `Review Board Contributor Guide`_ - + This generally applies to Djblets as well. + +We accept patches on `reviews.reviewboard.org +`_. (Please note that we *do not* accept pull +requests.) + +.. _Review Board Contributor Guide: + https://www.reviewboard.org/docs/codebase/dev://www.notion.so/reviewboard/Review-Board-45d228fb07a0459b84fee509ac054cec + + +Related Projects +================ + +* `Review Board`_ - + Our dedicated open source code review product for teams of all sizes. diff --git a/setup.py b/setup.py index 00421b2dd2005680dca4b9445d6875ac9aee16e4..f7190594326a22c26005bfe9dcd0a11e044da831 100755 --- a/setup.py +++ b/setup.py @@ -400,6 +400,10 @@ class InstallNodeDependenciesCommand(Command): test.run_tests = lambda *args, **kwargs: os.system('tests/runtests.py') +with open('README.rst', 'r') as fp: + long_description = fp.read() + + PACKAGE_NAME = 'Djblets' setup( @@ -410,6 +414,7 @@ setup( 'A collection of useful classes and functions for developing ' 'large-scale Django-based web applications.' ), + long_description=long_description, author='Beanbag, Inc.', author_email='reviewboard@googlegroups.com', url='https://www.reviewboard.org/downloads/djblets/',