landon/django-wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

initial

Browse Source
This commit is contained in:
lwark
2025-09-17 07:52:16 -05:00
commit a2ff72dda8
584 changed files with 52247 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/development/environment.rst Normal file
View File

@@ -0,0 +1,14 @@
Setting up a development environment
====================================
* Fork and clone the ``django-wiki`` repo from Github, ``cd`` into it.
* Install `hatch <https://hatch.pypa.io/latest/install/>`_ with your favorite package manager.
* Inside ``django-wiki`` directory, initialize the environment::
$ hatch env create
* Launch a new shell session in order to activate the environment::
$ hatch shell
* And done, you can start developing in ``django-wiki``.

255
docs/development/hatch.rst Normal file
View File

@@ -0,0 +1,255 @@
pyproject.toml and hatch
========================
Initially, django-wiki core devs opted to use the
new ``pyproject.toml`` and drop the old ``setup.py`` (see
:url-issue:`1199`). The Python packaging ecosystem has
standardized on the interface for build backends
(`PEP 517 <https://peps.python.org/pep-0517/>`_/`PEP 660 <https://peps.python.org/pep-0660/>`_)
and the format for metadata declaration (`PEP 621 <https://peps.python.org/pep-0621/>`_/`PEP 631 <https://peps.python.org/pep-0631/>`_).
As a result, the execution of ``setup.py`` files is now `deprecated <https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html>`_.
The discussion for this feature and the steps to mark this as completed are
happening `in this discussion <https://github.com/django-wiki/django-wiki/discussions/1226>`_,
and as well the development process is `here <https://github.com/django-wiki/django-wiki/pull/1227>`_.
As a result of this work, the maintainers opted to use ``hatch`` to manage the
development process of django-wiki, you can read more about it in their
`official docs <https://hatch.pypa.io/latest/>`_.
Assuming you have installed ``hatch`` in your environment, the first thing that
you have to do in a fresh copy of ``django-wiki`` is to initilize the
environments, for that you have to execute ``hatch env create`` in the root of
``django-wiki`` codebase.
This will add a set of available commands, and different environment that are
used in the development process, here's a list generated with ``hatch env show``::
Standalone
+-----------+---------+---------------------------+-------------+
| Name | Type | Dependencies | Scripts |
+===========+=========+===========================+=============+
| default | virtual | black<22.11,>=22.3.0 | assets |
| | | codecov | clean-build |
| | | coverage[toml] | clean-pyc |
| | | ddt | cov |
| | | django-functest<1.6,>=1.2 | lint |
| | | flake8<5.1,>=3.7 | no-cov |
| | | pre-commit | test |
| | | pytest-cov | |
| | | pytest-django | |
| | | pytest-pythonpath | |
| | | pytest<7.3,>=6.2.5 | |
+-----------+---------+---------------------------+-------------+
| transifex | virtual | transifex-client | assets |
| | | | clean-build |
| | | | clean-pyc |
| | | | cov |
| | | | lint |
| | | | no-cov |
| | | | pull |
| | | | push |
| | | | test |
+-----------+---------+---------------------------+-------------+
| docs | virtual | bleach<5.1,>=3.3.0 | assets |
| | | django>=3.1.13 | build |
| | | sphinx-rtd-theme==1.1.1 | changes |
| | | sphinx>=3 | clean |
| | | | clean-build |
| | | | clean-pyc |
| | | | cov |
| | | | devhelp |
| | | | dirhtml |
| | | | doctest |
| | | | epub |
| | | | gettext |
| | | | html |
| | | | htmlhelp |
| | | | info |
| | | | json |
| | | | latex |
| | | | latexpdf |
| | | | link-check |
| | | | link-check2 |
| | | | lint |
| | | | man |
| | | | no-cov |
| | | | pickle |
| | | | qthelp |
| | | | singlehtml |
| | | | test |
| | | | texinfo |
| | | | text |
+-----------+---------+---------------------------+-------------+
Matrices
+------+---------+-------------------+---------------------------+-------------+
| Name | Type | Envs | Dependencies | Scripts |
+======+=========+===================+===========================+=============+
| test | virtual | test.py3.7-dj2.2 | black<22.11,>=22.3.0 | all |
| | | test.py3.7-dj3.0 | codecov | assets |
| | | test.py3.7-dj3.1 | coverage[toml] | clean |
| | | test.py3.7-dj3.2 | ddt | clean-build |
| | | test.py3.8-dj2.2 | django-functest<1.6,>=1.2 | clean-pyc |
| | | test.py3.8-dj3.0 | flake8<5.1,>=3.7 | cov |
| | | test.py3.8-dj3.1 | pre-commit | lint |
| | | test.py3.8-dj3.2 | pytest-cov | no-cov |
| | | test.py3.9-dj2.2 | pytest-django | test |
| | | test.py3.9-dj3.0 | pytest-pythonpath | |
| | | test.py3.9-dj3.1 | pytest<7.3,>=6.2.5 | |
| | | test.py3.9-dj3.2 | | |
| | | test.py3.10-dj3.2 | | |
| | | test.py3.8-dj4.0 | | |
| | | test.py3.9-dj4.0 | | |
| | | test.py3.10-dj4.0 | | |
+------+---------+-------------------+---------------------------+-------------+
We have 4 different environments declared in the configuration file, each one
has his own purpose:
* ``default``: The development environment for django-wiki.
* ``test``: where we ensure that the code works on different Django and Python versions.
* ``docs``: Used for generate the page you're reading at this moment.
* ``transifex``: Used only for the translation side of the project.
We center around the entrypoints provided by ``hatch`` (`read more <https://hatch.pypa.io/latest/environment/#scripts>`_)
that's why we have documented commands that make development easier.
Some commands are only available in certain environments,
so for example at the ``transifex`` environment you see ``pull`` and ``push``
commands that are not present in any other environment declared above. For
executing the command you have to follow this simple formula::
$ hatch run <environment name>:<command name>
Then applied to the ``push`` command on the ``transifex`` environment will be::
$ hatch run transifex:pull
You can use the same logic to execute the available commands in the app, but
heres a detailed list of the commands ordered by environments, so you can
understand the purpose of each one:
* ``cov``: Check coverage status.
* ``no-cov``: Check places pending to add coverage.
* ``lint``: Make sure the code changes follow our guidelines and conventions.
* ``clean-build``: Remove the files generated after the project is built.
* ``clean-pyc``: Remove pyc generated files.
* ``assets``: Generate the static files used by django-wiki frontend.
* ``test``: Test the changes in the current environment.
* ``test:all``: Test the changes across our supported Python and Django versions.
* ``test:lint``: Make sure the code changes follows our guidelines and conventions.
* ``test:clean``: Remove the files generated via the testing process.
* ``transifex:push``: Push the translation files to Transifex.
* ``transifex:pull``: Pull the translation files from Transifex.
* ``docs:clean``: Remove the generated documentation files.
* List of docs commands used to generate the documentation in different formats:
* Please refer to the `Builder documentation of SPHINX <https://www.sphinx-doc.org/en/master/usage/builders/index.html>`_
to understand more about the purpose of each builder and the expected output.
* ``docs:html``
* ``docs:dirhtml``
* ``docs:singlehtml``
* ``docs:pickle``
* ``docs:json``
* ``docs:htmlhelp``
* ``docs:qthelp``
* ``docs:devhelp``
* ``docs:epub``
* ``docs:latex``
* ``docs:latexpdf``
* ``docs:text``
* ``docs:man``
* ``docs:texinfo``
* ``docs:info``
* ``docs:gettext``
* ``docs:changes``
* ``docs:link-check2``
* ``docs:doctest``
* ``docs:build``: Generate the documentation in HTML format.
* ``docs:link-check``: Checks for external links across the documentation.
We hope that this document helps you to understand more about the development
process, if something is not clear please open an issue.
FAQ
---
1. **Whats the difference between test and test:all?**
When you execute ``hatch run test`` this will check your changes in the
active environment, this means it will run over an specific Python version
and an specific Django Version; in the other hand ``test:all`` will run the
test suite in the whole matrix of the supported versions of Python and Django.
2. **hatch is unable to create a test environment with an specific Python Version?**
If after you execute ``hatch env create`` you receive a message like this in
your terminal ``py3.8-4.0 -> cannot locate Python: 3.8`` this means that
``hatch`` was unable to locate that Python version, in the end it depends on
what program do you use for manage your Python version, the most
important part is that the versions must be available in your ``PATH``.
3. **How to manage different Python Versions?**
There's a lot of options outside, the most important piece is that as stated
above, the versions need to able to be located in your system ``PATH``. for
example, if you're a user of `pyenv <https://github.com/pyenv/pyenv>`_ you
can set multiple Python version using ``pyenv local <version> <version>``.
``pyenv local 3.7.12 3.8.12 3.9.13 3.10.2``
4. **There's an error when init an environment?**
If you see and error message like ``Environment default defines a matrix, choose one of the following instead:``
and then a list of all of the available environments, you need to set the
environment name on the shell command like this ``hatch -e <env_name> shell``
``hatch -e test.py3.10-dj3.2 shell``
This way you can switch environments by an specific Python and Django version.
5. **How do I switch default shell versions?**
By default django-wiki runs on the latest supported Python and Django
version, if you want to swich to another environment, say for example
Python 3.9.13 with Django 3.0 then execute the following command:
``hatch -e py3.9-dj3.0 shell``

146
docs/development/index.rst Normal file
View File

@@ -0,0 +1,146 @@
Developer guide
===============
.. toctree::
:maxdepth: 1
hatch
environment
testproject
testing
.. highlight:: shell
Types of Contributions
----------------------
Report Bugs
~~~~~~~~~~~
Report bugs at https://github.com/django-wiki/django-wiki/issues.
If you are reporting a bug, please include:
* Your operating system name and version.
* Any details about your local setup that might be helpful in troubleshooting.
* Detailed steps to reproduce the bug.
Fix Bugs
~~~~~~~~
Look through the GitHub issues for bugs. Anything tagged with "bug"
and "help wanted" is open to whoever wants to implement it.
Implement Features
~~~~~~~~~~~~~~~~~~
Look through the GitHub issues for features. Anything tagged with "enhancement"
and "help wanted" is open to whoever wants to implement it.
Write Documentation
~~~~~~~~~~~~~~~~~~~
Django-wiki could always use more documentation, whether as part of the
official django-wiki docs, in docstrings, or even on the web in blog posts,
articles, and such.
Submit Feedback
~~~~~~~~~~~~~~~
The best way to send feedback is to file an issue at https://github.com/django-wiki/django-wiki/issues.
If you are proposing a feature:
* Explain in detail how it would work.
* Keep the scope as narrow as possible, to make it easier to implement.
* Remember that this is a volunteer-driven project, and that contributions
are welcome :)
Get Started!
------------
Ready to contribute? Here's how to set up `django-wiki` for local development.
#. Fork the `django-wiki` repo on GitHub.
#. Clone your fork locally::
$ git clone git@github.com:your_name_here/django-wiki.git
#. Go to your fork and install ``hatch`` which is the tool we use manage django-wiki
#. Install your local copy into a new environment. Assuming you have ``hatch`` installed, this is how you set up your fork for local development::
$ cd django-wiki/
$ hatch env create
#. Create a branch for local development::
$ git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
#. As you are making changes you may want to verify that changes are
passing all the relevant functional/unit tests::
$ hatch run test:all
#. If you made changes related to the style sheets (SCSS), you need to install `sassc <https://sass-lang.com/libsass>`__ (``sudo apt install sassc``) and run this to compile css::
$ hatch run assets
#. When you're done making changes, perform one final round of
testing, and also ensure relevant tests pass with all supported
Python versions with our matrix::
$ hatch run test
$ hatch run test:all # Runs all tests that pytest would run, just with various Python/Django combinations
#. Commit your changes and push your branch to GitHub::
$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature
#. Submit a pull request through the GitHub website.
Pull Request Guidelines
-----------------------
Before you submit a pull request, check that it meets these guidelines:
1. The pull request should include tests.
2. If the pull request adds functionality, the docs should be updated. Put
your new functionality into a function with a docstring, and add the
feature to the list in README.rst.
3. The pull request should work for Python 3.6, 3.7, 3.8 and for PyPy. Check
the status messages that are automatically generated for your pull request.
Tips
----
To run a subset of tests::
$ hatch run test:all tests/core/test_basic.py # All tests from a single file.
$ hatch run test:all tests/core/test_basic.py::URLPathTests # All tests from a single class.
$ hatch run test:all tests/core/test_basic.py::URLPathTests::test_manager # Just one test.
Roadmap
-------
The best way to contribute is to use our Github issue list to look
at current wishes. The list is found here:
https://github.com/django-wiki/django-wiki/issues/
If you want to add a feature, consider writing a plugin. Please create an
issue to discuss whether your plugin idea is a core plugin
(``wiki.plugins.*``) or external plugin. If there are additions needed
to the plugin API, we can discuss that as well! A discussion is always welcome
in a Github issue.
Generally speaking, we need more **unit tests** to improve coverage, and new
features will not be accepted without tests. To add more stuff to the project
without tests wouldn't be fair to the project or your hard work. We use coverage
metrics to see that each new contribution does not significantly impact test
coverage.

62
docs/development/testing.rst Normal file
View File

@@ -0,0 +1,62 @@
Tests
=====
Running tests
-------------
To run django-wiki's tests, you need to have installed ``hatch`` (read
more about it `here <https://hatch.pypa.io/latest/install/>`_) once installed
you can execute ``hatch run test:all`` to test your changes across our matrix.
To run **specific tests**, see ``hatch run test:all --help``.
To include Selenium tests, you need to have ``Xvfb`` installed
(usually via system-provided package manager), `chromedriver
<https://sites.google.com/a/chromium.org/chromedriver/>`_ and set the
environment variable ``INCLUDE_SELENIUM_TESTS=1``. For example, run
tests with (depending on whether you want to test directly or via
the test matrix)::
INCLUDE_SELENIUM_TESTS=1 hatch run test
INCLUDE_SELENIUM_TESTS=1 hatch run test:all
If you wish to also show the browser window while running the
functional tests, set the environment variable
``SELENIUM_SHOW_BROWSER=1`` in *addition* to
``INCLUDE_SELENIUM_TESTS=1``, for example::
INCLUDE_SELENIUM_TESTS=1 SELENIUM_SHOW_BROWSER=1 hatch run test:all
Writing tests
-------------
Tests generally fall into a few categories:
* Testing at the model level. These test cases should inherit from
``tests.base.TestBase``.
* Tests for views that return HTML. We normally use `django-functest
<http://django-functest.readthedocs.io/en/latest/>`_ for these, especially if
the page involves forms and handling of POST data. Test cases should inherit
from ``tests.base.WebTestBase`` and ``tests.base.SeleniumBase`` - see
``tests.core.test_views.RootArticleViewTestsBase``,
``RootArticleViewTestsWebTest`` and ``RootArticleViewTestsSelenium`` for an
example.
(In the past the Django test Client was used for these, and currently there
are still a lot of tests written in this style. These should be gradually
phased out where possible, because the test Client does a poor job of
replicating what browsers and people actually do.
* Tests for views that return JSON or other non-HTML. These test cases
should inherit from ``tests.base.DjangoClientTestBase``.
There are also other mixins in ``tests.base`` that provide commonly used
fixtures for tests e.g. a root article.
.. warning::
Views should be written so that as far as possible they work without
Javascript, and can be tested using the fast WebTest method, rather than
relying on the slow and fragile Selenium method. Selenium tests are not run by
default.

10
docs/development/testproject.rst Normal file
View File

@@ -0,0 +1,10 @@
Running the test project
========================
In order to quickly get setup, there is a project in the git repository.
The folder **testproject/** contains a pre-configured django project and
an sqlite database. Login for django admin is ``admin:admin``. This
project should always be maintained, but please do not commit changes to
the SQLite database as we only care about its contents in case data
models are changed.