Contributions¶

We welcome and encourage contributions of all nature; from pointing out an error or a potential problem, to translations, to feature requests, and pull requests.

We have a implemented a fully comprehensive developers' environment that comes with many functionalities, including its own Vagrant and Docker containers.

To set up the developers' environment, start off by cloning our source code from GitHub, like so:

git clone https://github.com/neutronX/django-markdownx.git

One that's done, change to the cloned directory and run:

python3 dev.py -h

to see the options available.

Quick reference¶

And here is what you will see:

Argument	Description
-h, --help	show the help message and exit.
-v, --vagrant	Install Vagrant development environment (requires Vagrant).
-d, --docker	Install Docker development environment (requires Docker).
-c, --clean	Clean up the development files (only the ones that have been automatically created).
-run-vagrant	Run vagrant development environment (runs --vagrant if the files don't already exist). Vagrant must be installed on your machine.
-run-docker	Run docker development environment (runs --docker if the files don't already exist). Docker must already be installed on your machine, and Docker Daemon must be up and running.
-no-container	Create development files without a container-based development environment (creates "manage.py" and "runtests.py").
--with-docs	Install documentation development environment.
--with-npm-settings	Install npm installation environment, including `package.jsonfor front-end (TypeScript) development (requiresnode.jsandnpm``).

• --with-docs and --with-npm-settings are optional and need to be accompanied by one of the required arguments.
• To save the changes made within the developers' environment, use -c or --clean; and you will be asked if you would like to override the existing settings. Do not commit your changes before doing this.

Example¶

This will install the following files:

• manage.py
• runtests.py
• Makefile
• create_docs.py

It will also install the requirements for compiling the documentations. You do not need to create the documentations locally if you do not intend to change them. Although you are welcome to do so, for minor changes, it is probably easier to report an issue on GitHub as compiling the documentations can be somewhat tricky.

python3 dev.py -no-container --with-docs

Once done, please run:

python3 dev.py -c

to clean the installed files. If any of them have been altered, you will be asked for additional instructions as to whether to save the changes or discard them and hold onto the default.

Tests¶

Django packages require manage.py and more often than not, settings.py files to run. This introduces a challenge for testing apps outside of a fully constructed project environment. This is one of the reasons why we introduced the developers' environment, which allows for a fully setup container (Vagrant or Docker) to create an inclusive virtual server that can be used to run MarkdownX independently.

To take advantage of this, you should clone the source code from GitHub as explained above, and depending on your container of choice, follow these instructions:

Vagrant¶

python3 dev.py --vagrant

Files will be created:

• Vagrantfile
• bootstrap.sh
• runtests.py
• manage.py
• package.json

python3 dev.py -run-vagrant

Connect to server using http://localhost:8000/ or http://127.0.0.1:8000/

Docker¶

python3 dev.py --docker

Files will be created:

• Dockerfile
• docker-compose.yml
• entrypoint.sh
• runtests.py
• manage.py
• package.json

python3 dev.py -run-docker

Connect to server using http://localhost:8000/ or http://127.0.0.1:8000/

---

Cleanup¶

Once done, please run:

python3 dev.py -c

to clean the installed files. If any of them have been altered, you will be asked for additional instructions as to whether to save the changes or discard them and hold onto the default.