Naive linter for English prose for developers who can't write good and wanna learn to do other stuff good too.
Detect non-inclusive language in your source code.
Vale is an open-source, command-line tool (, , and ) that brings your editorial style guide to life.
When I say "Legacy Code" I mean valuable code you're afraid to change.
We all have to deal with Legacy Code. But it's damn hard to!
Here you'll find answers to your questions. I'm sharing useful tips and concrete advice that will help you tame the legacy codebase you've inherited.
Change Messy Software Without Breaking It
In this tutorial, you’ll learn how to quickly build documentation for a Python package using MkDocs and mkdocstrings. These tools allow you to generate nice-looking and modern documentation from Markdown files and your code’s docstrings.
Maintaining auto-generated documentation means less effort because you’re linking information between your code and the documentation pages. However, good documentation is more than just the technical description pulled from your code! Your project will appeal more to users if you guide them through examples and connect the dots between the docstrings.
The Material for MkDocs theme makes your documentation look good without any extra effort and is used by popular projects such as Typer CLI and FastAPI.
There are several different docstring formats which one can use in order to enable Sphinx’s autodoc extension to automatically generate documentation. For this tutorial we will use the Sphinx format, since, as the name suggests, it is the standard format used with Sphinx. Other formats include Google (see here) and NumPy (see here), but they require the use of Sphinx’s napoleon extension, which is beyond the scope of this tutorial.
The Diátaxis framework aims to solve the problem of structure in technical documentation. It adopts a systematic approach to understanding the needs of documentation users in their cycle of interaction with a product.
The name Diátaxis comes from the Ancient Greek δῐᾰ́τᾰξῐς: dia (“across”) and taxis (“arrangement”).
Diátaxis identifies four modes of documentation - tutorials, how-to guides, technical reference and explanation. It derives its structure from the relationship between them.
In Diátaxis, each of these modes (or types) answers to a different user need, fulfils a different purpose and requires a different approach to its creation.
Do you document your code? Imagine that you need to get back to your code in 6 month after you wrote it, there is always a big possibility that you will have to spend some time to find out how this code works. Or if someone else wrote some code, which is already in production and your task is to fix a bug in it and there is no documentation and no one actually knows what this code does.
There are more benefits of implementing continuous documentation for the code:
easy to onboard new team members,
easy to share knowledge,
if this code is open source - easy to start contributing,
easy to see purpose and motivation of each piece of code,
easy to keep versioning for each new release of the code.It this talk I will show the difference between documentation types and will show a demo in the end of the talk.
This is the documentation wiki of FreeCAD. There are several ways to use this documentation: by exploring the hubs, by following the manual, or by using the Help menu entries from within FreeCAD. This is a work in progress, written by the community of users and developers of FreeCAD. If you find information that is wrong or missing, please help FreeCAD!
There is a secret that needs to be understood in order to write good software documentation: there isn’t one thing called documentation, there are four.
They are: tutorials, how-to guides, technical reference and explanation. They represent four different purposes or functions, and require four different approaches to their creation. Understanding the implications of this will help improve most documentation - often immensely.
Pleroma is a free, federated social networking server built on open protocols. It is compatible with GNU Social, Mastodon, and many other ActivityPub implementations.
Markdown is a lightweight markup language with a simplistic plain text formatting syntax. It exists in many syntactically different flavors. To support Markdown-based documentation, Sphinx can use MyST-Parser. MyST-Parser is a Docutils bridge to markdown-it-py, a Python package for parsing the CommonMark Markdown flavor.
Sphinx makes it easy to create intelligent and beautiful documentation.
Here are some of Sphinx’s major features:
-
Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text
-
Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information
-
Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children
-
Automatic indices: general index as well as a language-specific module indices
-
Code handling: automatic highlighting using the Pygments highlighter
-
Extensions: automatic testing of code snippets, inclusion of docstrings from Python modules (API docs) via built-in extensions, and much more functionality via third-party extensions.
-
Themes: modify the look and feel of outputs via creating themes, and re-use many third-party themes.
-
Contributed extensions: dozens of extensions contributed by users; most of them installable from PyPI.
Sphinx uses the reStructuredText markup language by default, and can read MyST markdown via third-party extensions. Both of these are powerful and straightforward to use, and have functionality for complex documentation and publishing workflows. They both build upon Docutils to parse and write documents.
Atlassian® Confluence® Builder for Sphinx is a community provided extension to help build Confluence supported format files (e.g. storage format) and publish them to a Confluence instance.
License: BSD-2-Clause
Confluence Cloud / Server 7.8+
Python 2.7 or 3.7+
Sphinx 1.8 or 4.1+
The community and development for this extension can all be found at this project's GitHub repository:
Atlassian Confluence Builder for Sphinx - GitHub
https://github.com/sphinx-contrib/confluencebuilder
The VMware Explore Content Catalog Is Live
The sessions, experts, labs and experiences you love and more from the center of the multi-cloud universe.
Docker can build images automatically by reading the instructions from a Dockerfile. A Dockerfile is a text document that contains all the commands a user could call on the command line to assemble an image. Using docker build users can create an automated build that executes several command-line instructions in succession.
This page describes the commands you can use in a Dockerfile. When you are done reading this page, refer to the Dockerfile Best Practices for a tip-oriented guide.
The VMware vCenter Server APIs are organized around REST. For ease of use and security, REST builds on the standard web protocols HTTP and HTTPS, using the normal network ports 80 and 443, which are both open in most data centers, and uses standard HTTP response codes, authentication, and verbs.
Using Ansible content that depends on non-default dependencies can be tricky. Packages must be installed on each node, play nicely with other software installed on the host system, and be kept in sync.
To help simplify this process, we have introduced the concept of Execution Environments, which you can create with Ansible Builder.
Visual Studio Code is a lightweight but powerful source code editor which runs on your desktop and is available for Windows, macOS and Linux. It comes with built-in support for JavaScript, TypeScript and Node.js and has a rich ecosystem of extensions for other languages (such as C++, C#, Java, Python, PHP, Go) and runtimes (such as .NET and Unity). Begin your journey with VS Code with these introductory videos.