Explore mkdocs instead of Sphinx.

[sobolevnrm]

It's just a suggestion, but if you are willing to make some changes, think mkdocs (material theme)
is widely used and much more intuitive than Sphinx, using markdown as the main format. Using
easier setup also means there will be more contributions. I'm happy to help if you are willing to at
least try it out!

Originally posted by @kiyoon in #422 (comment)

[sobolevnrm]

I'd like to explore this as a separate issue because we'll also need update RTD to make sure that https://pdb2pqr.readthedocs.io/ still works.

[kiyoon]

Sure, it's not urgent and it might take some work like docstring format changes to make it look as desired.

I have a template I will share, and some important commands and functionalities

[kiyoon]

This is a template I made, built with Mkdocs-Material with some plugins and configuration to make it more usable.

# mkdocs.yml

site_name: PDB2PQR
site_url: 'https://pdb2pqr.readthedocs.io'
repo_url: 'https://github.com/Electrostatics/pdb2pqr'
copyright: |
  &copy; 2025 <a href="https://www.poissonboltsmann.org"  target="_blank" rel="noopener">Poisson Boltsmann</a>
watch: [mkdocs.yml, README.md, pdb2pqr/]
validation:
  omitted_files: warn
  absolute_links: warn
  unrecognized_links: warn

nav:
  - Home:
      - Overview: index.md
      - Changelog: CHANGELOG.md
  - Menu A:
      - page A: pages/page_a.md
  # defer to gen-files + literate-nav
  - API reference:
      - mkdocstrings-python: reference/

theme:
  name: material
  font:
    text: Noto Sans Korean
    code: Jetbrains Mono
  features:
    - toc.follow
    - navigation.top
    - navigation.footer
    - navigation.sections
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.indexes
    - navigation.path
    - search.suggest
    - search.highlight
    - content.tabs.link
    - content.code.annotation
    - content.code.copy
  language: en
  palette:
    - media: '(prefers-color-scheme: light)'
      scheme: default
      primary: teal
      accent: purple
      toggle:
        icon: material/weather-sunny
        name: Switch to dark mode
    - media: '(prefers-color-scheme: dark)'
      scheme: slate
      primary: black
      accent: lime
      toggle:
        icon: material/weather-night
        name: Switch to system preference

plugins:
  - search
  - callouts:
      aliases: false
  - gen-files:
      scripts:
        - scripts/gen_ref_nav.py
  - literate-nav:
      nav_file: SUMMARY.md
  - mkdocstrings:
      handlers:
        python:
          options:
            show_symbol_type_heading: true
            show_symbol_type_toc: true
            members_order: source
            allow_inspection: false # for .pyi stubs to work
          paths: [src] # search packages in the src folder
# NOTE: pdb2pqr doesn't follow the src/ layout, so this should change.
# Empty or [pdb2pqr]? I think former but we need to try

extra:
  social:
    - icon: fontawesome/brands/github-alt
      link: https://github.com/Electrostatics/pdb2pqr
  version:
    provider: mike

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - admonition
  - pymdownx.arithmatex:
      generic: true
  - footnotes
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.mark
  - attr_list
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.tilde # strikethrough with ~~ ~~
  - toc:
      permalink: true
  # MathJax
  - pymdownx.arithmatex:
      generic: true

extra_javascript:
  - javascripts/mathjax.js
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js

extra_css:
  - stylesheets/extra_admonitions.css

Notes

• index.md will become index.html (the root page)

• I usually set index.md like

  --8<-- "README.md"

  This means the Github readme and the doc main page will be in sync.

Features

• Github style callouts (aka admonitions, alert, ...)

  > [!NOTE]
  > This is a NOTE type alert.

Note

This is a NOTE type alert.

• Latex style math equations
• Auto API reference generation using gen-files and literate-nav. Basically it will generate reference/*.md files and then add to the navigation menu when you build it.
• Flowchart with mermaid

```mermaid
graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];
```

graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];

Loading

Installation

mkdocs==1.6.1
mkdocs-autorefs==1.2.0
mkdocs-coverage==1.1.0
mkdocs-gen-files==0.5.0
mkdocs-literate-nav==0.6.1
mkdocs-material[imaging]==9.5.40
mkdocs-material-extensions==1.3.1
mkdocs-callouts==1.15.0
mkdocstrings==0.26.2
mkdocstrings-python==1.12.0
mike==2.1.3

docs/javascripts/mathjax.js for math support

window.MathJax = {
  tex: {
    inlineMath: [['\\(', '\\)']],
    displayMath: [['\\[', '\\]']],
    processEscapes: true,
    processEnvironments: true,
  },
  options: {
    ignoreHtmlClass: '.*|',
    processHtmlClass: 'arithmatex',
  },
}

document$.subscribe(() => {
  MathJax.startup.output.clearCache()
  MathJax.typesetClear()
  MathJax.texReset()
  MathJax.typesetPromise()
})

docs/stylesheets/extra_admonitions.css for two more github alert types: See sondregronas/mkdocs-callouts#22

Preview

mkdocs serve

[kiyoon]

The aim is that most pages will render on GitHub similarly, although not perfect. Of course, code references aren't supported by GitHub so those will be the ones not shown on GitHub.

[kiyoon]

https://github.com/kiyoon/mkdocs-material-github-flavored-template

I made this into a template repository. Hopefully it's easy to follow

[sobolevnrm]

How will files like https://github.com/Electrostatics/pdb2pqr/blob/master/docs/source/api/aa.rst get rendered using mkdocs?

[sobolevnrm]

The aim is that most pages will render on GitHub similarly, although not perfect. Of course, code references aren't supported by GitHub so those will be the ones not shown on GitHub.

The rendering isn't so bad right now; e.g., https://github.com/Electrostatics/pdb2pqr/blob/master/docs/source/extending.rst

[kiyoon]

The aim is that most pages will render on GitHub similarly, although not perfect. Of course, code references aren't supported by GitHub so those will be the ones not shown on GitHub.

The rendering isn't so bad right now; e.g., https://github.com/Electrostatics/pdb2pqr/blob/master/docs/source/extending.rst

I meant more like with using more advanced markdown features like

Note

This is an alert.

Tip

You can write some tips here

plus more like mermaid etc.

Plus, I wasn't comparing it with Sphinx because I don't know much about it actually, I just wanted to make markdown in mkdocs more compatible with GitHub style.

[kiyoon]

How will files like https://github.com/Electrostatics/pdb2pqr/blob/master/docs/source/api/aa.rst get rendered using mkdocs?

Something like this, but it slightly depends on the style option you choose to use.

• https://mkdocstrings.github.io/reference/loggers/
• https://kiyoon.kim/mkdocs-material-github-flavored-template/latest/reference/my_project/two_numbers/

[sobolevnrm]

It seems like a lot of work to convert from RestructedText to Markdown for essentially the same functionality with mkdocs as we get with Sphinx. Am I missing some new benefit we'd get with mkdocs?

[kiyoon]

No, Sphinx is completely feature-rich and you're not really missing much. The only difference is the base file format.

[sobolevnrm]

OK, mkdocs seems like a great solution for a new project but probably not worth the effort to convert PDB2PQR documentation right now. Thanks for bringing this up -- it was good to learn more about this alternative approach if we need it in the future.