From 3b3309a90eb0804921c559505eefd293359bb948 Mon Sep 17 00:00:00 2001 From: n Date: Sun, 17 Apr 2022 14:28:59 +0900 Subject: [PATCH] Minor fixes --- .../codeberg-pages/examples/docs-as-code.md | 43 +++++++++++-------- content/codeberg-pages/pushing-output.md | 40 ++++++++--------- content/getting-started/email-settings.md | 8 ++-- 3 files changed, 48 insertions(+), 43 deletions(-) diff --git a/content/codeberg-pages/examples/docs-as-code.md b/content/codeberg-pages/examples/docs-as-code.md index a07fd66..ad30a0b 100644 --- a/content/codeberg-pages/examples/docs-as-code.md +++ b/content/codeberg-pages/examples/docs-as-code.md @@ -3,10 +3,10 @@ eleventyNavigation: key: DocsAsCode title: "Example: Docs as Code with Sphinx" parent: CodebergPages - order: 101 + 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. @@ -14,9 +14,10 @@ To find out more about Docs-as-Code, head over to the official website: [https:/ 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 a static website hoster. -> **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 generatior (SSG) such as [Eleventy](https://www.11ty.dev/) or [Hugo](https://gohugo.io/), etc. +> **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. ## Building documentation with Sphinx @@ -30,13 +31,13 @@ To begin setting up your project, you will first need an account on Codeberg. If 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/). -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 virual 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. 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. -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 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: ```bash $ pip --version @@ -45,9 +46,10 @@ $ python --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. -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. +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. +> **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): @@ -56,10 +58,10 @@ $ cd ~/repositories/foobar $ 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. +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/``**. +> **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/``**. ### Activating the virtual environment @@ -121,7 +123,8 @@ With your virtual environment activated as shown above, it is now time to instal (.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. +> **Note** +> If you want to find out what the different arguments of **`pip install`** do, type the command **`pip install -h`** in your terminal. Once Sphinx is installed on your virtual environment, type the following command in your terminal: @@ -129,8 +132,8 @@ Once Sphinx is installed on your virtual environment, type the following command (.venv) $ pip sphinx-quickstart ``` -You will then be asked to answer a series of questions regarding the configuration of your project.
-Confirm that you want to **`Separate source and build directories`**. For the rest of the questions, keep pressing **Enter** to accept the default values and fill out the requested fields until you reach the question **`autodoc: automatically insert docstrings from modules`**, then choose **”y“ (yes)**. Keep pressing **Enter** again until you reach the question **`Create Makefile?`** and select **”y“ (yes)**. +You will then be asked to answer a series of questions regarding the configuration of your project. +Confirm that you want to **`Separate source and build directories`**. For the rest of the questions, keep pressing **Enter** to accept the default values and fill out the requested fields until you reach the question **`autodoc: automatically insert docstrings from modules`**, then choose **"y" (yes)**. Keep pressing **Enter** again until you reach the question **`Create Makefile?`** and select **"y" (yes)**. If you now run the `tree` command from your `mydocs` folder, you should get the following output: @@ -170,7 +173,8 @@ Once there, run the local python server with the command: (.venv) $ python3 -m http.server 8080 ``` -> **Note:**
“8080” is the TCP port on which the host server is listening for requests. +> **Note:** +> "8080" is the TCP port on which the host server is listening for requests. To access the default **`index.html`** file, type **`http://localhost:8080`** in your favorite browser. You should then see the default welcome page. @@ -183,13 +187,14 @@ You can start authoring your own content by creating a new reStructuredText file (.venv) $ touch mynewfile.rst ``` -You have just created an empty “.rst” file with the **`touch`** command. An “.rst” file is simply a plain text file that is written with reStructuredText as a markup language. To learn about how to use reStructuredText, follow the instructions provided in the article [reStructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html). +You have just created an empty ".rst" file with the **`touch`** command. An ".rst" file is simply a plain text file that is written with reStructuredText as a markup language. To learn about how to use reStructuredText, follow the instructions provided in the article [reStructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html). You will be more productive in your writing if you use a text editor that supports syntax highlighting such as [Emacs](https://www.gnu.org/software/emacs/download.html) or [Atom](https://atom.io/). Linux offers plenty of powerful text editors that support syntax highlighting and other advanced features for coding and authoring tasks. -> **Note:**
Whenever you create a new .rst file, you must add it manually to the `toctree` of your root document, i.e. “index.rst”. +> **Note:** +> Whenever you create a new .rst file, you must add it manually to the `toctree` of your root document, i.e. "index.rst". -The toctree directive (toc stands for Table of Contents) inserts a tree that connects the different “.rst” files located in your source directory with each other. Read the article [Directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#toctree-directive) to learn more about the toctree directive. +The toctree directive (toc stands for Table of Contents) inserts a tree that connects the different ".rst" files located in your source directory with each other. Read the article [Directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#toctree-directive) to learn more about the toctree directive. 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. diff --git a/content/codeberg-pages/pushing-output.md b/content/codeberg-pages/pushing-output.md index 4e4daf1..50a7494 100644 --- a/content/codeberg-pages/pushing-output.md +++ b/content/codeberg-pages/pushing-output.md @@ -5,38 +5,39 @@ eleventyNavigation: parent: CodebergPages author: Fayçal Alami Hassani - https://codeberg.org/ka2in date: January 2022 - order: 100 + order: 101 --- In case you are using a static site generator (SSG) and that you are satisfied with the result of your project on the local development environment, you can push the files to your Codeberg repository. To begin with, we will make sure to have two separate repositories, both locally and on Codeberg: -- A main repository for the source files, i.e. where the source files related to your main project will be located. We will refer to this repository as the `source` repository. This repository is the one associated with your [mydocs](#mydocs) folder. +- A main repository for the source files, i.e. where the source files related to your main project will be located. We will refer to this repository as the `source` repository. This repository is the one associated with your [mydocs](/codeberg-pages/examples/docs-as-code/#mydocs) folder. -- A second repository for Codeberg pages, that we will call the `deployment` repository. This repository will only contain the files available in the `html` folder located under: +- A second repository for Codeberg pages, that we will call the `pages` repository. This repository will only contain the files available in the `html` folder located under: ```bash (.venv) $ cd docs/build/html ``` -> **Note:**
For the purpose of this guide, we have chosen to use two separate folders/repositories. However, you may want to have a different setup that involves creating a [submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules) instead of having folders and repositories on separate locations. With a submodule, you configuration should look as follows: +> **Note:** +> For the purpose of this guide, we have chosen to use two separate folders/repositories. However, you may want to have a different setup that involves creating a [submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules) instead of having folders and repositories on separate locations. With a submodule, your configuration should look as follows: +> +> ```bash +> ├── sources --> This is a git repo +> │ ├── build +> │ │ └── html +> │ │ └── pages --> This is a separate git repo +> │ └── content +> ``` + +To copy the content of the `html` folder to your new `pages` folder, run the command: ```bash -├── sources --> This is a git repo -│ ├── build -│ │ └── html -│ │ └── deployment --> This is a separate git repo -│ └── content +(.venv) $ cp -R docs/build/html/ pages ``` -To copy the content of the `html` folder to your new `deployment` folder, run the command: - -```bash -(.venv) $ cp -R docs/build/html/ deployment -``` - -We will now initialize an empty repository inside the deployment folder. To do so, type the command: +We will now initialize an empty repository inside the pages folder. To do so, type the command: ```bash $ git init @@ -66,8 +67,7 @@ Repeat these steps also in your `source` folder, then push your local commits to $ git push origin HEAD:your-remote-branch-name ``` -> **Note:**
Replace `your-remote-branch-name` by the actual name of your remote branch. It is recommended to intially push your commits to a different branch than the `master` or `main` branch. Once you have made sure everything went smoothly, you can then make a pull request to merge contents. To learn more about “pull requests”, read the article [Pull requests and Git flow](https://docs.codeberg.org/collaborating/pull-requests-and-git-flow/). +> **Note:** +> Replace `your-remote-branch-name` by the actual name of your remote branch. It is recommended to initially push your commits to a different branch than the `master` or `main` branch. Once you have made sure everything went smoothly, you can then make a pull request to merge contents. To learn more about pull requests, read the article [Pull requests and Git flow](https://docs.codeberg.org/collaborating/pull-requests-and-git-flow/). -To publish the web content of your `deployment` folder on Codeberg, follow the procedure described under the section [Codeberg Pages](https://docs.codeberg.org/codeberg-pages/). - -You should now be able to visit your content under the following link: `https://{user-name}.codeberg.page`. \ No newline at end of file +You should now be able to visit your content under the following link: `https://{user-name}.codeberg.page`. You can find more information in the [Codeberg Pages](/codeberg-pages/) section. \ No newline at end of file diff --git a/content/getting-started/email-settings.md b/content/getting-started/email-settings.md index ece00d7..8b0d998 100644 --- a/content/getting-started/email-settings.md +++ b/content/getting-started/email-settings.md @@ -6,13 +6,13 @@ eleventyNavigation: order: 65 --- -By default, the Gitea instance of Codeberg will send notifications to your registered email address(es). +By default, the Gitea instance of Codeberg will send notifications to your registered email addresses. ## Configuring all notifications -To change your notification preferences, go to your [user settings](https://codeberg.org/user/settings/account) or manually navigate to the settings. +To change your notification preferences, go to your [Account Settings](https://codeberg.org/user/settings/account) or manually navigate to the settings page. -You can access the settings by clicking on the menu button “Profile and Settings...” in the top-right corner. From there, navigate to Settings > Account > Manage Email Addresses. +You can access it by clicking on the menu button “Profile and Settings...” in the top-right corner of Codeberg. From the dropdown, click on Settings, then click on the Account tab. In the section “Manage Email Addresses”, you can select one of the following options from the drop-down menu for each email address that you registered with Codeberg: @@ -25,7 +25,7 @@ In the section “Manage Email Addresses”, you can select one of the following Press the button “Set Email Preference” to confirm your selection. > **Note:** -> disabling email notifications does not mean that you will stop receiving important communication from the Codeberg organisation. +> Disabling email notifications does not mean that you will stop receiving important communication from the Codeberg organisation. ## Issue notifications