diff --git a/content/codeberg-pages/examples/docs-as-code.md b/content/codeberg-pages/examples/docs-as-code.md index ad30a0b..d253dac 100644 --- a/content/codeberg-pages/examples/docs-as-code.md +++ b/content/codeberg-pages/examples/docs-as-code.md @@ -6,18 +6,18 @@ eleventyNavigation: order: 100 --- -Docs-as-Code (also known as "Documentation as Code") refers to the concept of treating documentation as a codebase, i.e. integrating the documentation process in the toolchains and workflows used by software development teams. +Docs-as-code (also known as "Documentation as Code") refers to the concept of treating documentation as a codebase, i.e. integrating the documentation process in the toolchains and workflows used by software development teams. -Docs-as-Code involves implementing versioning capabilities for your documentation projects and authoring your content with plain text markup languages such as Markdown or reStructuredText, among other things. +Docs-as-code involves using version control systems such as Git for your documentation projects and authoring your content with plain text markup languages such as Markdown or reStructuredText, among other things. -To find out more about Docs-as-Code, head over to the official website: [https://docs-as-co.de/](https://docs-as-co.de/). +To find out more about docs-as-code, head over to [its website](https://docs-as-co.de/). -Whether you are a single technical communicator or a member of a larger documentation team, you can perfectly apply the Docs-as-Code approach to your documentation projects. +Whether you are a single technical communicator or a member of a larger documentation team, you can perfectly apply the docs-as-code approach to your documentation projects. -This guide will show you how to implement Docs-as-Code on a Linux machine using ["Sphinx"](https://www.sphinx-doc.org/en/master/) as a documentation generator, ["Git"](https://ka2in.codeberg.page/gitinminutes.html) as a version control system and ["Codeberg Pages"](https://docs.codeberg.org/codeberg-pages/) as a static website hoster. +This guide will show you how to implement docs-as-code on a Linux machine using [Sphinx](https://www.sphinx-doc.org/en/master/) as a documentation generator, [Git](https://ka2in.codeberg.page/gitinminutes.html) as a version control system and [Codeberg Pages](https://docs.codeberg.org/codeberg-pages/) as static site hosting. > **Note** -> Despite the fact that we are using Sphinx in this particular case, please note that you can easily apply the instructions provided below to any other static site generator (SSG) such as [Eleventy](https://www.11ty.dev/) or [Hugo](https://gohugo.io/), etc. +> Despite the fact that we are using Sphinx in this particular case, you can easily apply these instructions to any static site generator (SSG) such as [Eleventy](https://www.11ty.dev/) or [Hugo](https://gohugo.io/). ## Building documentation with Sphinx @@ -27,31 +27,31 @@ Sphinx uses [reStructuredText](https://docutils.sourceforge.io/docs/user/rst/qui ### Setting up the project -To begin setting up your project, you will first need an account on Codeberg. If you do not already have one, follow the instructions provided under [Your First Steps on Codeberg](https://docs.codeberg.org/getting-started/first-steps/). +To begin setting up your project, you will first need an account on Codeberg. If you don't already have one, follow the instructions provided under [Your First Steps on Codeberg](https://docs.codeberg.org/getting-started/first-steps/). -This guide assumes that you already have Git installed on your machine. If this is not the case, please proceed as described in the article [Install Git](https://docs.codeberg.org/getting-started/install-git/). +This guide assumes that you already have Git installed on your machine. If you don't, you can install git as described in the article [Install Git](https://docs.codeberg.org/getting-started/install-git/). -For the purpose of this guide, we will start a documentation project from scratch using an empty repository. To create a new, empty repository and clone it to your local workspace, follow the steps described in the article [Your First Repository](https://docs.codeberg.org/getting-started/first-repository/) as well as the instructions provided under "Option A: Clone the newly created, empty repository" within the same article. +For the purpose of this guide, we will start a documentation project from scratch using an empty repository. To create a new empty repository and clone it to your local workspace, follow the steps described in the article [Your First Repository](https://docs.codeberg.org/getting-started/first-repository/) as well as the instructions provided under "Option A: Clone the newly created, empty repository" within the same article. ### Creating a Python virtual environment -A "virtual" isolated environment comes in very handy to eliminate the risk of any broken dependencies while working on your projects. Put in other words, setting up a virtual environment for your project allows you to run an instance of the Python interpreter with a particular package set and a specific configuration while ensuring compatibility between all these components inside that environment. +A "virtual" isolated environment comes in very handy to eliminate the risk of any broken dependencies while working on your projects. In other words, setting up a virtual environment for your project allows you to run an instance of the Python interpreter with a particular package set and a specific configuration while ensuring compatibility between all these components inside that environment. -Before proceeding with this task, you should make sure that you have "pip" and "python" installed on your machine. To perform a preliminary check, type the following commands in your terminal: +Before starting, you should make sure that you have pip and Python 3 installed on your machine. To check, type the following commands in your terminal: ```bash $ pip --version -$ python --version +$ python3 --version ``` -If pip and Python are not already installed on your Linux machine, please follow the steps described in the articles [pip Installation](https://pip.pypa.io/en/latest/installation/) and [Installing Python 3 on Linux](https://docs.python-guide.org/starting/install3/linux/) respectively. +If pip and Python are not installed on your Linux machine, please follow the steps described in the articles [pip Installation](https://pip.pypa.io/en/latest/installation/) and [Installing Python 3 on Linux](https://docs.python-guide.org/starting/install3/linux/) respectively. Depending on your Python version, you will need to install a compatible virtual environment manager, i.e. either "venv" for Python >= 3.3, or "virtualenv" for older Python versions. > **Note** > Please note that Python2 has reached its EOL (End of Life) on January 1st 2020, which means that it is no longer receiving any security updates. If you are using Python 3.3 or higher, you do not need to install the "venv" module, since it is already available in your Python standard library. -The next step consists in creating a virtual environment. To do so, navigate to the folder where you have cloned the repository described under the section [Setting up the project](#setting-up-the-project): +The next step is to create a virtual environment. To do so, navigate to the folder where you have cloned the repository described under the section [Setting up the project](#setting-up-the-project): ```bash $ cd ~/repositories/foobar @@ -61,16 +61,17 @@ $ python3 -m venv env You can replace the second argument "env" with any other name your like. This will be the folder hosting your virtual environment. > **Important** -> Use a **``.gitignore``** file to exclude your virtual environment directory from your version control system. To ignore the entire "env" folder, you just have to include the corresponding path and append a **``/``** at its end, e.g. **``env/``**. +> Use a **``.gitignore``** file to exclude your virtual environment directory from your version control system. To ignore the entire "env" folder, include the corresponding path and append a **``/``** at its end, e.g. **``env/``**. ### Activating the virtual environment Before you begin performing any tasks on your project, you must activate your virtual environment by running the following command: ```bash -$ source env/bin/activate +$ . env/bin/activate ``` -To make sure that you are working inside your virtual environment, run the command: + +To make sure that you are working inside of your virtual environment, run the command: ```bash $ which python @@ -79,10 +80,10 @@ $ which python The output of the command above should be the **`env`** folder, e.g.: ```bash -$ ./env/bin/python +./env/bin/python ``` -Whenever you are done working on your project, run the following command to leave the virtual environment: +When you are done working on your project, run the following command to leave the virtual environment: ```bash $ deactivate @@ -92,7 +93,7 @@ $ deactivate If you have followed the steps described up to this point, your local repository should now contain your virtual environment's folder **`env`** in addition to the hidden **`.git`** directory and the **`.gitignore`** file that we have already described at the end of the section [Creating a Python virtual environment](#creating-a-python-virtual-environment), e.g.: -```bash +``` ├── myproject │ ├── env │ ├── .git @@ -100,14 +101,14 @@ If you have followed the steps described up to this point, your local repository ``` -You will now create an empty directory then navigate to it. For the purpose of this guide, we will call our directory `mydocs`. Note that you can choose any other name you like: +You will now create an empty directory then navigate to it. For the purpose of this guide, we will call our directory `mydocs`. You can choose any name you'd like: ```bash $ mkdir mydocs $ cd mydocs ``` -Running the command `tree -a` should now give you the following output: +Running the command `tree -a` should now output the following: ```bash . @@ -117,14 +118,14 @@ Running the command `tree -a` should now give you the following output: └── .gitignore ``` -With your virtual environment activated as shown above, it is now time to install Sphinx with the `pip` tool. To do so, run the command: +With your virtual environment activated as shown above, it is now time to install Sphinx with `pip`. To do so, run the following: ```bash (.venv) $ pip install -U sphinx ``` > **Note** -> If you want to find out what the different arguments of **`pip install`** do, type the command **`pip install -h`** in your terminal. +> If you wish to learn about the different options of **`pip install`** are, run the command **`pip install -h`**. Once Sphinx is installed on your virtual environment, type the following command in your terminal: @@ -153,7 +154,7 @@ Congratulations! 🎉 You have just finished installing Sphinx on your Linux mac ### Running a local HTTP server using Python -To set up a local testing server for your documentation project, you can use the Python module **`http.server`**. To do so, you will first have to build the html resources for the initial test by running the command: +To set up a local testing server for your documentation project, you can use the Python module **`http.server`**. To do so, you will first have to build the HTML resources for the initial test by running the command: @@ -161,7 +162,7 @@ To set up a local testing server for your documentation project, you can use the (.venv) $ sphinx-build -b html docs/source/ docs/build/html ``` -Then navigate to the directory hosting the html resources: +Then navigate to the directory hosting the HTML resources: ```bash (.venv) $ cd docs/build/html @@ -180,7 +181,7 @@ To access the default **`index.html`** file, type **`http://localhost:8080`** in ### Creating files with reStructuredText and checking the output -You can start authoring your own content by creating a new reStructuredText file (.rst) in the source directory: +You can start creating your own content by making a new reStructuredText file (.rst) in the source directory: ```bash (.venv) $ cd mydocs/source @@ -198,4 +199,4 @@ The toctree directive (toc stands for Table of Contents) inserts a tree that con Once you have added an .rst file to the `toctree`, you can check the output at any time by running the [sphinx-build](#running-a-local-http-server-using-python) command illustrated above, then refreshing your local testing server. -If you are satisfied with the result on your local development environment, you can publish the content on Codeberg Pages. To find out how to achieve this, read the article [Pushing output from SSGs into Codeberg Pages](https://docs.codeberg.org/codeberg-pages/pushing-output/). \ No newline at end of file +If you are satisfied with the result on your local development environment, you can publish the content on Codeberg Pages. To find out how to do this, read the article [Pushing output from SSGs into Codeberg Pages](https://docs.codeberg.org/codeberg-pages/pushing-output/).