#mkdocs

[algoentremanos]

Cómo convertir todas tus entradas de WordPress a Markdown

Cómo convertir todas tus entradas de WordPress a Markdown #WordPress #MarkDown #Obsidian

Últimamente, tengo una fijación enorme con tener más controlada la información, y por eso, tenerla toda en Markdown se ha convertido en una prioridad. Por eso hoy te voy a contar cómo transformar tu blog WordPress a Markdown de manera sencilla. Lo vas a poder hacer gracias a la exportación de WordPress a XML y luego usando wordpress-export-to-markdown en tu ordenador. Generamos un archivo XML…

[aozhangchina]

Material for Mkdocs设置

MkDocs 材料提供了多种自定义文档的选项。在本节中，我们将解释如何为您的网站创建有意义的结构、更改外观和感觉、添加博客和评论系统以及构建高度优化的网站。 颜色 颜色主题 MkDocs 的 Material 支持两种配色方案：浅色模式（简称 default）和深色模式（称为 slate）。颜色方案可以通过 mkdocs.yml 进行设置：  theme:  palette:    scheme: default 可选参数：default、slate 基本颜色 主要颜色用于标题、侧边栏、文本链接和其他几个组件。要更改主要颜色，请在 mkdocs.yml 中将以下值设置为有效的颜色名称：  theme:  palette:    primary: indigo 可选参数：red、pink、purple、deep purple、indigo、blue、light…

[hasufin]

My not-bright person would possibly be a little less confused if people who don't do documentation work didn't keep directing them to things which are not markdown editors and saying to use them for editing markdown.

I get they REALLY don't like the answer of "Use a basic text editor", but... it's Markdown. Use a basic text editor. Do not tell this person to use Word, it doesn't do Markdown; do not tell them to use Oxygen, it's an XML editor; do not tell them to use mkdocs, it's not an editor at all. Poor fool is wandering around whimpering because they're being told to use a shovel to change a car tire.

[souhaillaghchimdev]

Developing Open Source Programming Libraries

Open source libraries are essential tools that drive innovation and collaboration in the programming world. They help developers save time, encourage knowledge sharing, and improve software quality. If you've ever thought about giving back to the developer community, building your own open source library is a fantastic way to start.

What is a Programming Library?

A programming library is a collection of reusable code, functions, or classes that help developers perform common tasks without rewriting code from scratch. Examples include libraries for handling dates, making HTTP requests, or performing complex mathematical operations.

Why Build an Open Source Library?

Contribute to the community: Help other developers solve problems and build better software.

Enhance your skills: Learn software design, testing, and documentation.

Build your reputation: Demonstrate your knowledge and gain recognition in the dev community.

Get feedback: Collaborate with developers from around the world and improve your code.

Steps to Build an Open Source Library

Identify a Problem: Find a common pain point or a repetitive task that you can simplify with code.

Plan Your Library: Outline features, structure, and language-specific conventions.

Write Clean Code: Use modular, readable, and well-documented code.

Include Tests: Unit and integration tests ensure your library works as expected.

Write Documentation: Explain how to install, use, and contribute to your library.

Choose a License: Pick an open source license (like MIT, GPL, Apache) to define how others can use your code.

Publish Your Library: Share it on GitHub and package it for ecosystems like npm (JavaScript), PyPI (Python), or crates.io (Rust).

Tools You Might Use

Git & GitHub: For version control and collaboration.

CI/CD Tools: Like GitHub Actions for automating tests and deployments.

Package Managers: npm, pip, Maven, etc., depending on your language.

Documentation Tools: JSDoc, Sphinx, or MkDocs to generate professional docs.

Best Practices

Keep your code simple and focused on solving one problem well.

Write thorough documentation and usage examples.

Be responsive to issues and pull requests.

Encourage contributions and create a welcoming community.

Use semantic versioning (SemVer) for clear version management.

Example: A Simple JavaScript Utility Library

Here's a snippet of a function that could go in a utility library: // utils.js export function capitalize(str) { return str.charAt(0).toUpperCase() + str.slice(1); }

You can package this as an npm module and publish it with clear usage instructions and tests.

Conclusion

Building an open source library is a great way to level up as a programmer while making a real impact. Whether it's a simple utility or a full-featured framework, your library can help others while showcasing your skills. Start small, stay consistent, and join the world of open source contributors!

[ai-news]

Use Markdown to quickly create a beautiful documentation page for your projectsContinue reading on Towards Data Science » #AI #ML #Automation

[klymilark]

Kristell L.

Complete aside, I'm working on a website for the #WurmOnline alliance I'm in, and I can't figure out if I wanna use #hexo or #mkdocs for it. I'm leaning more towards mkdocs, since it doesn't look like a blog and does more look like a wiki, but also the categories feature of hexo is nice because I don't have to update 3 pages when someone new joins. Time to try and figure it out https://ift.tt/l1s3f5W

[nandithamn]

Best Practices for Python Code Documentation

INTRODUCTION

Documentation in Python code is crucial for ensuring readability, maintainability, and collaboration within a project. Here are some best practices for effective Python code documentation@ www.nearlearn.com:

Describe our code. ...

Create docstrings for all public classes, methods, functions, and modules. ...

Create appealing documentation with Sphinx

Adopt a unified style. ...

Incorporate illustrations in the writing. ...

Describe limitations. ...

Don't document internal information. ...

Maintain a changelog…

By following these best practices, you can create Python code that is well-documented, easy to understand, and a pleasure to work with for both yourself and other developers.

You can always stop and review the resources linked here if you get stuck.

Top of Form

Your Environment for Building Documentation. ...

Create the Sample Python Package. ...

Write and Format Your Docstrings. ...

Prepare Your Documentation With MkDocs.

Best code documentation for python is :

Is far and away the most popular Python training tool. Use it. It converts reStructuredText markup language into a range of output formats including HTML, LaTeX (for printable PDF versions), manual pages, and plain text. There is also great, free hosting for your

Certainly! Here's a comprehensive guide to best practices for documenting Python code:

Use Meaningful Variable and Function Names: Clear and descriptive names reduce the need for excessive comments by making the code self-explanatory.

Follow PEP 8 Guidelines: Adhere to the Python Enhancement Proposal (PEP) 8 style guide for consistent code formatting, including comments and docstrings.

Use Docstrings: Write docstrings for modules, classes, functions, and methods. Docstrings provide inline documentation that can be accessed via tools like help Use Triple Quotes for Multiline Docstrings Triple quotes allow for multiline docstrings, enabling comprehensive documentation for complex functions or classes.

Follow the Google Style Docstring Format: Adopt the Google style docstring format for consistency and compatibility with popular documentation generators like Sphinx. This format includes sections such as "Args", "Returns", "Raises", and "Examples".

Document All Parameters and Return Values: Clearly document all parameters accepted by functions or methods, along with their types and purposes. Document the expected return values and their meanings.

Document Exception Handling: If a function raises exceptions under certain conditions, document those conditions and the types of exceptions that may be raised.

Provide Usage Examples: Include usage examples in your docstrings to illustrate how to use functions or methods effectively. Real-world examples help users understand the intended usage.

Update Documentation Regularly: Keep documentation up-to-date with code changes. Outdated documentation can mislead users and cause confusion.

Use Documentation Generators: Utilize documentation generators like Sphinx, Pdoc, or Doxygen to automate the generation of documentation from your codebase. These tools can produce professional-looking documentation in various formats.

Include Module-Level Documentation: Provide an overview of each module's purpose, contents, and usage at the beginning of the file. This summary helps users quickly grasp the module's functionality.

Document Class Interfaces: Document class interfaces, including methods, properties, and their purposes. Describe how to instantiate objects and interact with them.

Include Version Information: Specify the version of your code in the documentation. Users should know which version of the code they are referencing to ensure compatibility.

Document Public APIs Thoroughly: Document all public APIs extensively, including their parameters, return values, exceptions, and usage examples. Well-documented APIs facilitate easier integration and usage by other developers.

By following these best practices, you can ensure that your Python code is well-documented, easy to understand, and accessible to users and collaborators. Best institute in Bangalore is nearlearn visit our page https://nearlearn.com/python-online-training.

[geone-ws]

Switch to #OpenStreetMap

https://andygol.co.ua/switch2osm-mkdocs/

[openscreencast]

mkdocs - eine Dokumentation im HTML-Format generieren Lizenz: http://creativecommons.org/licenses/by/4.0/

http://www.mkdocs.org/ http://www.mkdocs.org/user-guide/configuration/ https://www.gitbook.com/ http://www.sphinx-doc.org/en/stable/ https://github.com/rust-lang-nursery/mdBook https://www.staticgen.com/

[algoentremanos]

Cómo conectar MkDocs con GitHub y controlar los cambios de tu documentación

Cómo conectar MkDocs con GitHub y controlar los cambios de tu documentación #Mkdocs #Obsidian #Github

Ya te he contado cómo montar tu web estática de manera sencilla con MkDocs, pero ahora vamos un paso más allá: vamos a conectar esa web, tus documentos .md con un repositorio de GitHub para llevar un control de cambios de tu documentación. Es muy sencillo. Instalamos Git en nuestro ordenador ¿Pasos previos? Tienes que tener instalado Git en tu ordenador. En macOS lo he instalado gracias a…

[aozhangchina]

Material for Mkdocs中文教程

Material for MkDocs 是 MkDocs 之上的强大文档框架，MkDocs 是项目文档的静态站点生成器。如果您熟悉 Python，则可以使用 Python 包管理器 pip 安装 Material for MkDocs。 注：中文教程只提供最简单的设置，更多内容请查看官网 https://squidfunk.github.io/mkdocs-material/getting-started 开始 Material for MkDocs 以 Python 包的形式发布，可以使用 pip 进行安装，最好使用虚拟环境进行安装。打开一个终端并使用以下命令安装 Material for MkDocs：  pip install mkdocs-material 这将自动安装所有依赖项的兼容版本：MkDocs、Markdown、Pygments 和 Python…

[admiswalker]

2020/12/30

学生の本分が勉強なら，社会人の本分は労働． 2020 年も本日 30 日と明日 31 日を残すのみとなった． GitHub のコミット履歴を辿ると，今年は 1 ～ 6 月ごろまで競技プログラミング (≒AtCoder) の過去問題をひたすらに埋め，7 ～ 12 月の初頭までを，古いアイデアの整理と再実験に費やしていたようだ． AtCoder については，過去問だけ説いて，レーティングを測らないというチキン野郎なので，来年はどこかで測ろうと思う．実力を隠したからといって，強くなれる訳でもあるまい． 古いアイデアについては，整理した内容を元指導教官に見て頂いた．（大変迷惑な卒業生だと思う）． 少し懸念していた通り，やはり分野がいくらかズレていたりと，トラブルもあったものの，爪の甘さを教えて頂き，大変有意義であった．結果が実るかどうかは分からないが，また修正していきたい．迷惑度合いについては，把握しかねており，また様子を伺ってみたい．（上手くできるだろうか．．．） ここ数日は，久々の気分転換として，好きなこと (≒自作ライブラリの拡張) をやろうと思った，，，のだが，まずは，古い自作ライブラリのドキュメント環境を整え，過去の活動を整理することにした． ドキュメント環境を MkDocs をベースに Makefile を用いて 1) 自動コンパイル と 2) 実行結果の貼り付け の 2 つの機能を強引に追加した．かなり汚いが 2 ～ 3 日で実装できたので，良しとしよう．(このあたり，C++ の日本語リファレンスのシステムは，上手くやっていると思う．こちらは，HTML の出力まで自作？だろうか)． 機能追加の甲斐もあり，12 月 25 日から 30 日現在までに 50 個くらいのサンプルコードを実装している．といっても，Markdown を書くだけで済むので，非常に楽である．今までドキュメントを書かないのはよくないな，と思いつつ，書けなかったのは，結局のところ，ドキュメントを楽に書ける環境を，用意する実力が無かったのだろう． もちろん，Doxygen のようなドキュメントシステムを使ってもよかったのだが，私としては，使い方のサンプルを一緒に乗せられるようなシステムが欲しかった． さて，冒頭の表題に戻ると，社会人の本分は労働である． 今年は趣味全開だった業後の時間も，ある程度業務を見据えて方向性を合わせる必要がありそうだ．お給料をもらっている以上，給与分の働きはしたいものだが，こんな時代であるから，会社との心中は避けたい． 自分を見失わず，会社と社会の向かう方向も気にしながら，2021 年も乗り越えていきたい．

[ai-news]

Making documentation come to lifeContinue reading on Towards Data Science » #AI #ML #Automation

[datamattsson]

The Perfect Documentation Storm

Let’s be clear. Nobody likes writing documentation. Writing good documentation is also hard. Making it look visually pleasing can be even more challenging. I’ve been involved with a project aimed to make user documentation easy to consume but also easy for anyone to contribute to. My north star for good documentation is the Ansible documentation. It’s visually very pleasing, easy to find stuff and it’s all there. Google does a damn good job indexing it so whatever you need is three keywords away. The project at hand is not capable of leveraging some of magic sauces behind the Ansible documentation project but I found a middle ground that completely blew my away. From here on forward this is the toolchain I will recommend for all and any documentation project: MkDocs and GitHub Pages.

Requirements

The bulk of our starting source docs today is all written in markdown and we were not interested in converting to a new “language” or learn a new one. It has to be version controlled, human readable and reviewable markdown. It disqualifies a bunch of different popular tools out there, but hear me out her. So, GitHub is an excellent place to store, version and review markdown files, let's start there.

Next, there needs to be a way to edit and review the markdown rendering locally (or remotely) efficiently before submitting pull requests. It should not be counter-productive with multiple tools, renders and manual refresh/walkthrough navigation to get visual feedback. As we sniffed around other successful documentation projects we learned about MkDocs as we investigated the capabilities of Read The Docs. Little did we know that MkDocs lets you render and edit docs locally very efficiently, it’s widely used, extensible and looks beautiful out-of-the-box. Just add markdown!

Also, MkDocs can deploy directly to GitHub Pages by putting the rendered output in a separate branch and all of a sudden you have everything in one place. That alone makes it very convenient as we don’t have to interact with separate services to host the documentation. One might think we’re done here but it leaves one big gap in the solution, that is the reviewing of pull requests part. In the event of a pull request, the person who merges to master needs to render the pages after the merge. You may quickly resort to readthedocs.org for this reason but what if I told you that there is a GitHub Action available that does this for you already? That changes the game. Full control end-to-end through GitHub. Let's do it!

Hello World

Since it wasn’t glaringly obvious to me on how to piece everything together, I thought I share my findings in this blog. Let’s walk through a Hello World example where we start with nothing.

First, create a new empty GitHub repo and clone it (you need to create your own repo as my demo repo won't work).

$ git clone https://github.com/drajen/hello-docs Cloning into 'hello-docs'...

Next, we need to install mkdocs if you haven’t already. Acquiring Python and pip is beyond the scope of this tutorial.

$ sudo pip install mkdocs

Change dir into the hello-docs directory and run:

$ cd hello-docs $ mkdocs new . INFO - Writing config file: ./mkdocs.yml INFO - Writing initial docs: ./docs/index.md

The mkdocs command creates the docs directory, this is where your source markdown lives. A skeleton index.md is populated with some MkDocs metadata. There’s also a starter mkdocs.yml file that allows you to configure your project. I want to use the Read The Docs theme, so, let’s configure that:

$ echo 'theme: readthedocs' >> mkdocs.yml

Next, we want to visually inspect what the documentation looks like:

$ mkdocs serve INFO - Building documentation... INFO - Cleaning site directory [I 200311 16:29:05 server:296] Serving on http://127.0.0.1:8000 [I 200311 16:29:05 handlers:62] Start watching changes [I 200311 16:29:05 handlers:64] Start detecting changes

Browsing to http://127.0.0.1:8000/ should now present the following website:

In an attempt to try illustrate how the local editing works, I generated a GIF from a screen capture. Simply edit text in your favorite editor (vi) and hit :w. The content will automatically be rebuilt and reloaded based on your markdown edits.

This is awesome!

Publish!

Not quite done yet. To demonstrate the next steps, we need to publish our site. Let’s add site/ (where the local build lives) to .gitignore and push our content.

$ echo 'site/' >>.gitignore $ git add . $ git commit -a -m 'Initial hack...' $ git push origin master

Next, have MkDocs publish to the gh-pages branch.

$ mkdocs gh-deploy INFO - Cleaning site directory INFO - Building documentation to directory: /Users/mmattsson/code/hello-docs/site WARNING - Version check skipped: No version specificed in previous deployment. INFO - Copying '/Users/mmattsson/code/hello-docs/site' to 'gh-pages' branch and pushing to GitHub. INFO - Your documentation should shortly be available at: https://drajen.github.io/hello-docs/

Visiting the URL MkDocs spits out above should be rendered in a few moments. It’s possible to tweak the URL by setting a custom domain for GitHub Pages under the repository settings. You’ll need a DNS CNAME pointing to <user/org>.github.io for that to work properly.

Action!

Now the skeleton is published. How do we accept pull requests and have the gh-pages branch rebuilt on merge to master? This GitHub Action does that exact job for you.

It only works reliably with personal tokens. A token is generated on your user account and a secret is part of the repository settings.

So, in the middle bar you’ll find an “Actions” tab, create a new workflow and paste in the YAML from the Deploy MkDocs GitHub Action. Don’t forget to change the token attribute!

Now, this GitHub Action will run for each merge to master, that makes it easy to accept pull requests for markdown. If big navigational changes is in the PR, it could make sense to clone the pull request and render the branch locally. That will allow visual inspection of the navigation and check for errors in the MkDocs build log.

Happy documenting!

[syndicode]

Frontend documentation style guides

In our material about custom software development process stages we talked about the need of good documentation. But aren’t words just words without a proper example? This time we’d like to show you some frontend documentation style guides with best practices. Thanks to the good...

[youjirec]

カンタンにドキュメントが作れるmkdocsが便利すぎる話 - Qiita 今回は、mkdocsと呼ばれるマークダウンでwebサイトが作れるツールを使ってみたので説明してみようと思います。 趣味でいろんなデバイスを作っているわみがお伝えします。