pyvec / pyvec/docs.pyvec.org

Consider moving to MkDocs

Open
#434 11 comments 4 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
13
Forks
18
Avg merge
2h 42m
Merged PRs (30d)
5

Description

Just an idea. Pros:

  • Simpler stack, simpler config.
  • Markdown has won. People don't know reST, even myself, after years of using it, still make the most basic mistakes and need to lookup the most basic stuff.
  • Also supported by RTD.
  • Has the Material theme, which is modern, under active development, flexible, has dark theme, etc.
  • Is used at other projects, such as python.cz or junior.guru, so know-how would be shared (contributions, maintenance).

Cons:

  • We extend Sphinx and would need to rewrite those things.
  • We use reST extensively. I'm not sure we can port it 1:1 (but is it necessary?)

How:

  • This can happen gradually. Our current setup supports Markdown, so texts can be converted first and we would see.
  • I already moved from builtin Sphinx link check to Lychee, as it works better.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review the current Sphinx configuration and existing Markdown and reST documentation, then compare the custom extensions with MkDocs and its Material theme. Check the existing Lychee link-check setup and the feasibility of gradual Markdown conversion. The issue names no files or acceptance criteria, so an agreed migration scope and definition of done are still needed.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.