Skip to content
This repository has been archived by the owner on Feb 28, 2022. It is now read-only.

Sphinx DocFX YAML is an exporter for the Sphinx Python domain into DocFX YAML format.

License

Notifications You must be signed in to change notification settings

docascode/sphinx-docfx-yaml

Repository files navigation

Sphinx DocFX YAML

https://travis-ci.org/docascode/sphinx-docfx-yaml.svg?branch=master

Sphinx DocFX YAML is an exporter for the Sphinx Autodoc module into DocFX YAML.

You can read the full documentation online at http://sphinx-docfx-yaml.readthedocs.io

Contents

.. toctree::
   :glob:
   :maxdepth: 2

   design
   layout
   api

Basic Workflow

  • Write RST that includes Python autodoc
  • Render internal doctree into YAML
  • Output YAML into output directory

Install

First you need to install docfx-yaml:

pip install sphinx-docfx-yaml

Then add it to your Sphinx project's conf.py:

# Order matters here.
# The extension must be defined *after* autodoc,
# because it uses a signal that autodoc defines
extensions = ['sphinx.ext.autodoc', 'docfx_yaml.extension']

Make sure you are using autodoc in your code somewhere:

.. automodule:: foo.bar

Then build your documentation:

make html

Inside your build directory (_build/html usually), the docfx_yaml will contain the YAML files that are output.

Design

Read more about the design in our :doc:`design`.

Layout

This project has a few different pieces at this point. It's primary goal was to integrate the Azure Python SDK into the docfx tooling. You can read more about the pieces currently set up in the :doc:`layout`.

Napoleon Support

We support sphinx.ext.napoleon for parsing docstrings in other formats. Currently all markup that maps to existing Sphinx info field lists will work, along with Examples. In order to pull examples out, you need the napoleon_use_admonition_for_examples set to True.

About

Sphinx DocFX YAML is an exporter for the Sphinx Python domain into DocFX YAML format.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages