Skip to main content

Sphinx Python Domain to DocFX YAML Generator

Project description

Sphinx DocFX YAML
=================

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

.. image:: https://ci.appveyor.com/api/projects/status/m9t5a331de14mwfi/branch/master?svg=true
:target: https://ci.appveyor.com/project/ericholscher/sphinx-docfx-yaml

Sphinx DocFX YAML is an exporter for the Sphinx Autodoc module into `DocFX YAML <https://dotnet.github.io/docfx/spec/metadata_format_spec.html>`_.

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 <www.sphinx-doc.org/en/stable/ext/autodoc.html>`_
* Render internal doctree into YAML
* Output YAML into output directory

Install
-------

First you need to install docfx-yaml:

.. code:: bash

pip install sphinx-docfx-yaml

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

.. code:: python

# 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.

.. Modes
-----

There are two output modes that specify the structure of the YAML files.
The first is ``module`` which means that the YAML files will be output in files corresponding to the name of their module.
The second modes is ``rst`` which outputs them in the same structure as the RST files they were defined in.

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 <http://www.sphinx-doc.org/en/stable/domains.html#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``.

Project details


Release history Release notifications

History Node

1.2.33

History Node

1.2.32

History Node

1.2.31

History Node

1.2.30

History Node

1.2.29

History Node

1.2.28

History Node

1.2.27

History Node

1.2.26

History Node

1.2.25

History Node

1.2.24

History Node

1.2.23

History Node

1.2.22

History Node

1.2.21

History Node

1.2.20

History Node

1.2.19

History Node

1.2.18

History Node

1.2.17

History Node

1.2.16

History Node

1.2.15

History Node

1.2.14

History Node

1.2.13

History Node

1.2.12

History Node

1.2.11

History Node

1.2.10

History Node

1.2.9

History Node

1.2.8

History Node

1.2.7

This version
History Node

1.2.6

History Node

1.2.5

History Node

1.2.4

History Node

1.2.3

History Node

1.2.2

History Node

1.2.1

History Node

1.2.0

History Node

1.1.0

History Node

1.0.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
sphinx-docfx-yaml-1.2.6.tar.gz (19.6 kB) Copy SHA256 hash SHA256 Source None Jun 19, 2017

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page