Posts about Dendron / Docs as Code / DevOps / Linux / AWS / PowerShell / Python / Automating All The Things. Opinions expressed are my own, not those of my employer.
I've tried tools like Jekyll and Hugo, both of which I still use for blogs, but they didn't meet requirements for certain documentation projects.
Now I'm a huge fan of Sphinx: which is open-source, and doesn't require any licensing. It can use Markdown or reStructuredText (rST). rST has become my go-to, and has seemed capable of doing more things within Sphinx out-of-box.
Sphinx can be used for general documentation, but can also automatically generate documentation from Python docstrings in code repositories, Javascript projects (thanks to efforts by Mozilla), and even Go or .NET with other extensions: all by pulling from comment blocks to make use of documentation from within the code base itself.
If arguments/options are already being documented within the code, then why not extract it to add to the separately written docs?
Automation can be introduced to documentation around things like spelling and URL link validation.
Automation pipelines can include jobs that generate PDFs (Sphinx uses things like LaTeX/LuaTex/XeTeX/etc.) and even ePUB files from the documentation, too, rather than just the HTML static site.
I'm thinking of creating some quickstart projects that use GitLab/GitHub Pages, and GitLab CI / GitHub Actions for automatically building and deploying websites in a GitOps fashion. I'll be including PDF generation as part of the pipelines.
I do have some biases here, though, like using Python as my tool of choice. Sphinx is python-based. I've also been wanting to create tooling that can generate a blog but also an ebook/PDF from blog contents. That, and even print-ready PDFs with proper formatting for print-on-demand (POD) style printers like KDP. I also have many projects that cross-reference each other, so that idea of importing compatible rst files from other source repos was ideal.
Sphinx is something I've been meaning to check out! A lot of open source projects use it, so it seems useful to know how it works when contributing to a project.
I'm thinking of creating some quickstart projects that use GitLab/GitHub Pages, and GitLab CI / GitHub Actions for automatically building and deploying websites in a GitOps fashion. I'll be including PDF generation as part of the pipelines.
I would be really interested in reading a write up on how you do this, if you ever have the time!
Posts about Dendron / Docs as Code / DevOps / Linux / AWS / PowerShell / Python / Automating All The Things. Opinions expressed are my own, not those of my employer.
I wanted to update here: I did a rather major pivot toward adopting Dendron, so I want to make sure to mention it here. My long-term goal is to use LaTeX and other tooling that make use of the Markdown notes and docs I take in Dendron. I have converted my main website over to using it: icanteven.io/
A major difference for Dendron is that it isn't just meant to be a publishing tool from a CLI, though that is a definite feature. Dendron is a VSCode / VSCodium extension that provides an excellent UX for knowledge management in general, which the other tools (such as Hugo, Sphinx, Jekyll, etc.) don't have. This has made my life easier, and having the ability to pull documentation from multiple vaults (git repos of documentation) into a single workspace, and to selectively publish a collection of documentation, is really cool.
Now, I've even joined the Dendron team! We cross-post under the Dendron dev.to org here, and the documentation is at wiki.dendron.so. I highly recommend it, and to checkout the growing Discord Community.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
I've tried tools like Jekyll and Hugo, both of which I still use for blogs, but they didn't meet requirements for certain documentation projects.
Now I'm a huge fan of Sphinx: which is open-source, and doesn't require any licensing. It can use Markdown or reStructuredText (rST). rST has become my go-to, and has seemed capable of doing more things within Sphinx out-of-box.
Sphinx can be used for general documentation, but can also automatically generate documentation from Python docstrings in code repositories, Javascript projects (thanks to efforts by Mozilla), and even Go or .NET with other extensions: all by pulling from comment blocks to make use of documentation from within the code base itself.
If arguments/options are already being documented within the code, then why not extract it to add to the separately written docs?
Automation can be introduced to documentation around things like spelling and URL link validation.
Automation pipelines can include jobs that generate PDFs (Sphinx uses things like LaTeX/LuaTex/XeTeX/etc.) and even ePUB files from the documentation, too, rather than just the HTML static site.
I'm thinking of creating some quickstart projects that use GitLab/GitHub Pages, and GitLab CI / GitHub Actions for automatically building and deploying websites in a GitOps fashion. I'll be including PDF generation as part of the pipelines.
I do have some biases here, though, like using Python as my tool of choice. Sphinx is python-based. I've also been wanting to create tooling that can generate a blog but also an ebook/PDF from blog contents. That, and even print-ready PDFs with proper formatting for print-on-demand (POD) style printers like KDP. I also have many projects that cross-reference each other, so that idea of importing compatible rst files from other source repos was ideal.
Sphinx is something I've been meaning to check out! A lot of open source projects use it, so it seems useful to know how it works when contributing to a project.
I would be really interested in reading a write up on how you do this, if you ever have the time!
I wanted to update here: I did a rather major pivot toward adopting Dendron, so I want to make sure to mention it here. My long-term goal is to use LaTeX and other tooling that make use of the Markdown notes and docs I take in Dendron. I have converted my main website over to using it: icanteven.io/
A major difference for Dendron is that it isn't just meant to be a publishing tool from a CLI, though that is a definite feature. Dendron is a VSCode / VSCodium extension that provides an excellent UX for knowledge management in general, which the other tools (such as Hugo, Sphinx, Jekyll, etc.) don't have. This has made my life easier, and having the ability to pull documentation from multiple vaults (git repos of documentation) into a single workspace, and to selectively publish a collection of documentation, is really cool.
Now, I've even joined the Dendron team! We cross-post under the Dendron
dev.toorg here, and the documentation is at wiki.dendron.so. I highly recommend it, and to checkout the growing Discord Community.