Python venv cheat sheet for MKDocs¶
MKDocs is an easy-to-use python static site generator that makes writing and publishing to the web a breeze. But you firstly need a virtual python environment on your local machine, as long as it's not an immutable distro you will be fine. read about Nixos here
Installation¶
Make sure python is installed on your computer. It's best to first set up a python virtual environment, that will only contain the python packages that are specific to your particular project.
This allows us to separate the global python on your pc, and will make it easier to manage your machine and your projects going forward.
Venv can be used easily for this purpose, with the following command:
The placeholder "blog" denotes the path to the virtual environment that you want to create.You now need to activate the environment with the following command:
On Linux:
On Windows:
Please ensure that the virtual environment is activated
For this command to work, make sure you are in the same directory where the virtual environment was installed. If sucessful, on the shell you will see a parenthesis on the left hand side with the name of the activated virtual environment. In this case you should see (blog) johnny@linux:~/$
Next you can continue to install the python libraries that you need for your project using pip.
All subsequent python packages and libraries will be installed only to the virtual environment that you have created. This keeps your system clean and avoids conflicts with global python.
When you're finished developing your specific project, you can deactivate the virtual environment by simply typing:
Python uses a configuration file that lists all the packages used for a particular project called "requirements.txt"
While in the activated virtual environment, you can run the following command to create this file:
This file can later be used to deploy specific python code dependencies to a production server or another computer.
For full documentation visit mkdocs.org
MKDocs commands¶
mkdocs new [dir-name]
- create a new projectmkdocs serve
- Start the live reloading docs servermkdocs build
- Build the documentation sitemkdocs -h
- Print the help message and exit
Project layout¶
mkdocs.yml # The configuration file.
docs/
index.md # The documentation homepage.
... # Other makedown pages, images and other files