diff --git a/docs/guide/tools/index.rst b/docs/guide/tools/index.rst index 7100c8c7f4..6f459715c1 100644 --- a/docs/guide/tools/index.rst +++ b/docs/guide/tools/index.rst @@ -2,14 +2,38 @@ Tools for documentation writing ================================ -Writing documentation requires good tools. -There are a bunch of different tools in the world, -but we figure we should give you the sharpest. -Below we talk about some of our favorites and the ones we find do the job -the best. +Writing documentation requires good tools. This section covers documentation tools recommended by the Write the Docs community, with a focus on tools widely used for technical documentation. + +Sphinx +------ + +Sphinx is a documentation generator widely used in the Python ecosystem and beyond. It converts reStructuredText (and Markdown via MyST Parser) into HTML, PDF, and other formats. Sphinx excels at technical documentation with features like code introspection, cross-referencing, and multiple output formats. + +See the following pages for Sphinx guidance: + +.. toctree:: + :maxdepth: 2 + + sphinx + sphinx-themes + sphinx-community + +Other documentation tools +------------------------- + +While this section currently focuses on Sphinx, the Write the Docs community uses many documentation tools depending on project needs: + +- **MkDocs**: Markdown-focused static site generator with live preview +- **Docusaurus**: React-based tool by Meta with built-in versioning and i18n +- **Jekyll**: Ruby-based static site generator, popular for GitHub Pages +- **Hugo**: Extremely fast Go-based generator for content sites + +See the main :doc:`/guide/index` for broader documentation guidance applicable across tools. + +Testing and quality +------------------- .. toctree:: :maxdepth: 2 - :glob: - * + testing diff --git a/docs/guide/tools/sphinx-community.rst b/docs/guide/tools/sphinx-community.rst new file mode 100644 index 0000000000..a7ba1da994 --- /dev/null +++ b/docs/guide/tools/sphinx-community.rst @@ -0,0 +1,37 @@ +Community perspectives on Sphinx +================================== + +This page captures common experiences and feedback from the Write the Docs community about using Sphinx, based on discussions at Write the Docs Portland 2021 and ongoing community conversations. + +What users appreciate +--------------------- + +Community members frequently highlight Sphinx's strengths for technical documentation: + +- Code introspection and tight integration with source code (docs-as-code approach) +- Powerful reStructuredText markup for complex documentation needs +- Intersphinx for cross-linking between projects +- Strong domain support for multiple programming languages + +Common challenges +----------------- + +New users often encounter similar hurdles when learning Sphinx: + +**Learning curve**: Sphinx presents a significant barrier to entry, particularly for those new to documentation tools or reStructuredText. + +**Navigation setup**: Creating and managing toctree structures requires careful planning and can be unintuitive initially. + +**Documentation style**: The official Sphinx documentation is comprehensive but geared toward reference rather than learning. New users often benefit from supplementary tutorials like those listed in the :doc:`/guide/tools/sphinx` introduction. + +**Theming**: Customizing Sphinx themes requires understanding the templating system, which can be challenging. The :doc:`/guide/tools/sphinx-themes` page provides recommended starting points. + +Resources and community +----------------------- + +The Sphinx community continues to create learning resources to address the steep learning curve: + +- `Sphinx Tutorial `_ - Official tutorial for newcomers +- `Read the Docs Getting Started `_ - Step-by-step guide + +Join the #sphinx channel on the Write the Docs Slack to connect with other Sphinx users and get help. diff --git a/docs/guide/tools/sphinx-themes.rst b/docs/guide/tools/sphinx-themes.rst index b32ab4198c..fa530ba2d0 100644 --- a/docs/guide/tools/sphinx-themes.rst +++ b/docs/guide/tools/sphinx-themes.rst @@ -1,9 +1,9 @@ Sphinx themes ============= -These are the Sphinx themes that we recommend. -If there are any others you like, -feel free to open a pull request to add them. +These are Sphinx themes that the Write the Docs community recommends. +The Sphinx ecosystem includes many themes - this list highlights popular, well-maintained options. +If there are others you like, feel free to open a pull request to add them. Requirements to be included on this list: @@ -84,3 +84,17 @@ designed navigation features (sidebar, inter-page links). .. image:: /_static/img/furo.png :width: 80% + +PyData Sphinx theme +------------------- + +A clean, three-column, Bootstrap-based theme widely adopted by scientific and data science projects. Features responsive design and excellent navigation for complex documentation. + +* https://github.com/pydata/pydata-sphinx-theme + +Shibuya +------- + +A modern, responsive theme with excellent light/dark mode support and great integration with Jupyter extensions. Features Radix color system and flexible layouts. + +* https://github.com/lepture/shibuya diff --git a/docs/guide/tools/sphinx.rst b/docs/guide/tools/sphinx.rst index a624a0db5e..934720777f 100644 --- a/docs/guide/tools/sphinx.rst +++ b/docs/guide/tools/sphinx.rst @@ -182,3 +182,27 @@ You can now open them in your browser by typing:: open _build/html/index.html +Markdown support +---------------- + +While Sphinx primarily uses reStructuredText, it can also work with Markdown files using the MyST Parser. MyST (Markedly Structured Text) extends CommonMark Markdown with features needed for technical documentation while maintaining compatibility with Sphinx's ecosystem. + +To use Markdown in your Sphinx project, install myst-parser and configure it in ``conf.py``. You can mix ``.rst`` and ``.md`` files in the same project. + +* `MyST Parser documentation `_ + +Key features and extensions +---------------------------- + +Sphinx includes powerful features for technical documentation: + +**Intersphinx**: Cross-reference documentation from other Sphinx projects without duplicating content. Particularly valuable for projects with multiple interconnected documentation sites. + +* `Intersphinx documentation `_ + +**Domains**: Built-in support for documenting Python, C, C++, JavaScript, and reStructuredText code with specialized directives and roles. Extensions available for other languages. + +**Extensions ecosystem**: Large collection of extensions for specialized needs (autodoc, viewcode, todo, napoleon, and many more). + +* `Extensions documentation `_ + diff --git a/vale/WTD/headings.yml b/vale/WTD/headings.yml index 1e40483e4c..91c3a15f53 100644 --- a/vale/WTD/headings.yml +++ b/vale/WTD/headings.yml @@ -17,6 +17,7 @@ exceptions: - Git - Guzzle - HTMLProofer + - PyData - Read the Docs - README - SEO