Docs-as-Code with Sphinx and Codeberg Pages #198

Please note that internal links should already get auto-created for headlines, you can reuse them.

Adjusted accordingly, thanks.

I suppose this is a leftover?

Yes, removed.

could you drop the whitespace below?

I am not quite sure if your website really makes sense here. Of course you wrote this article and you should be honored but I think your name and email adress (if you want) or your codeberg profile url would make more sense here

Adjusted accrodingly.

I think a toc would be really great. Not sure whether there are auto-generated ones yet

I don't know, either. Should explore this later.

there is an extra whitespace before deployment

"deployment" is the target folder. You're copying the content from docs/build/html/ into a new folder named "deployment".

Please make sure to stick to the markdown formatting rules. This lines should look like this:

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:

Notice the empty line before We will now...

Done.

I did not really understand the setup. I think you ment:

├── sources --> This is a git repo
│  ├── build
│  │  └── html
│  │  └── deployment --> This is a separate git repo
│  └── content

If thats the case I would suggest creating a submodule. Correct my if I am wrong though. But still this architecture with a submodule would probably make more sense than having separate folders/repos.

You're right. Creating a submodule is the way to go. Somehow, I had some issues upon creating a submodule, and then decided to have separate folders/repos.
I will add a corresponding note and suggest creating a submodule.

you can then make a pull request to merge contents.

Many people might not know what a PR is so why not link to the PR documentation of codeberg: https://docs.codeberg.org/collaborating/pull-requests-and-git-flow/

Done.

Maybe add a note at the end: For further information about Docs-as-Code head over to their official website: https://docs-as-co.de/ or something like that.

Note added.

Well your example with Sphinx is pretty good but you could at a note there that this could also easily applied to any other static site generatior such as eleventy or hugo etc.

Done.

Please add an emty line before the code block

Empty line added.

Is there a reason for the whitespace after the <br />

No. Whitespace removed.

You already said that Python2 has reached its EOL. Why should we continiue documenting Python2 specific stuff

No, we should not. But people use outdated software on some occasions, and the purpose of user-friendly documentation is to help people regardless of their technical background or level of expertise.

Same as the above with Python2

Adjusted accordingly.

You could add an example output there:

./env/bin/python

Example added.

You could at the output of the tree command there

├── myproject
│  ├── env
│  ├── .git
│  └── .gitignore

Done.

As @fnetX already mentioned you can use the header links (e.g. http://localhost:8080/codeberg-pages/#1.-setting-up-the-project)

This is in the middle of a section, right? Makes sense to add a custom link there if really necessary.

Sometimes you are using one backtick ` inline, sometimes two backticks `` and now I see even three backticks ```. I am not quite sure if there is a difference but if not please use a single backtick ` inline and three backticks ``` for code blocks

Done.

Same as the above: Use the generated header links

Done.

This is of course a workaround until we manage to implement sub-categories but still it is unclear that this section is related to the pages section

├── Codeberg Pages
│  └── Troubleshooting
└── Examples
 ├── Docs as Code
 └── Pushing output from SSGs into Codeberg Pages

This is what it looks like on the web view.

Maybe rename the section to Codeberg Pages - Examples, or something like that, for now

The "Pushing output" ... better fits below Codeberg Pages below. Also, I don't like the new Section approach, can we keep this structure for filenames (URLs + on disk tree, future proof / avoid renames in the future)

─── Codeberg Pages
	├── Troubleshooting
	├── Pushing output from SSGs into Codeberg Pages
	└── Examples
		└── Docs as Code with Spinx

But this for the sidebar (using the eleventy parent tools that don't have to be equal to how it's structured on the disk)

─── Codeberg Pages
	├── Troubleshooting
	├── Pushing output from SSGs into Codeberg Pages
	└── Example: Docs as Code with Spinx

I don't mind whether the generic instruction of how to push SSG output to pages resides under Examples or Codeberg Pages directly.

It makes more sense to keep the example with Sphinx above the article about pushing output into Codeberg Pages. You first test on your local environment, and once you're satisfied with the result, you push the output into Codeberg Pages.

I tend to disagree. Pushing output to Codeberg Pages is relevant for much more people than the specific example about Spinx. Also, these steps can be learned independently (While I get that your tutorial like initial writeup is kind-of separated now, you can learn how to push something to pages first, then consider if you like it, and then consider if you want this specific example).

But I won't block this with an inverted order if you insist.

Order inverted.
The initial intention was to introduce the user to the concept of "Docs-as-Code". Consequently, the user tests something on the local environment, then pushes the output into Codeberg Pages.