Merge pull request #32611 from openedx/feanil/platform-docs
feanil/platform docs
This commit is contained in:
Feanil Patel
15
Makefile
15
Makefile
@@ -1,5 +1,5 @@
|
||||
# Do things in edx-platform
|
||||
.PHONY: api-docs-sphinx api-docs base-requirements check-types clean \
|
||||
.PHONY: base-requirements check-types clean \
|
||||
compile-requirements detect_changed_source_translations dev-requirements \
|
||||
docker_auth docker_build docker_push docker_tag docs extract_translations \
|
||||
guides help lint-imports local-requirements pre-requirements pull \
|
||||
@@ -23,24 +23,17 @@ clean: ## archive and delete most git-ignored files
|
||||
tar xf $(PRIVATE_FILES)
|
||||
rm $(PRIVATE_FILES)
|
||||
|
||||
SWAGGER = docs/swagger.yaml
|
||||
SWAGGER = docs/lms-openapi.yaml
|
||||
|
||||
docs: api-docs guides technical-docs ## build all the developer documentation for this repository
|
||||
docs: guides technical-docs ## build all the developer documentation for this repository
|
||||
|
||||
swagger: ## generate the swagger.yaml file
|
||||
DJANGO_SETTINGS_MODULE=docs.docs_settings python manage.py lms generate_swagger --generator-class=edx_api_doc_tools.ApiSchemaGenerator -o $(SWAGGER)
|
||||
|
||||
api-docs-sphinx: swagger ## generate the sphinx source files for api-docs
|
||||
rm -f docs/api/gen/*
|
||||
python docs/sw2sphinxopenapi.py $(SWAGGER) docs/api/gen
|
||||
|
||||
api-docs: api-docs-sphinx ## build the REST api docs
|
||||
cd docs/api; make html
|
||||
|
||||
technical-docs: ## build the technical docs
|
||||
$(MAKE) -C docs/technical html
|
||||
|
||||
guides: ## build the developer guide docs
|
||||
guides: swagger ## build the developer guide docs
|
||||
cd docs/guides; make clean html
|
||||
|
||||
extract_translations: ## extract localizable strings from sources
|
||||
|
||||
2
docs/api/.gitignore
vendored
2
docs/api/.gitignore
vendored
@@ -1,2 +0,0 @@
|
||||
_build
|
||||
gen
|
||||
@@ -1,19 +0,0 @@
|
||||
# Minimal makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line.
|
||||
SPHINXOPTS =
|
||||
SPHINXBUILD = sphinx-build
|
||||
SOURCEDIR = .
|
||||
BUILDDIR = _build
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
.PHONY: help Makefile
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
218
docs/api/conf.py
218
docs/api/conf.py
@@ -1,218 +0,0 @@
|
||||
# lint-amnesty, pylint: disable=missing-module-docstring
|
||||
#
|
||||
# Configuration file for the Sphinx documentation builder.
|
||||
#
|
||||
# This file does only contain a selection of the most common options. For a
|
||||
# full list see the documentation:
|
||||
# http://www.sphinx-doc.org/en/master/config
|
||||
|
||||
|
||||
import os
|
||||
|
||||
from datetime import datetime
|
||||
|
||||
# -- Path setup --------------------------------------------------------------
|
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
#
|
||||
# import os
|
||||
# import sys
|
||||
# sys.path.insert(0, os.path.abspath('.'))
|
||||
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
|
||||
project = 'Open edX REST APIs'
|
||||
copyright = f'{datetime.now().year}, Axim Collaborative, Inc' # pylint: disable=redefined-builtin
|
||||
author = 'Axim Collaborative, Inc'
|
||||
|
||||
# The short X.Y version
|
||||
version = ''
|
||||
# The full version, including alpha/beta/rc tags
|
||||
release = ''
|
||||
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
|
||||
# If your documentation needs a minimal Sphinx version, state it here.
|
||||
#
|
||||
# needs_sphinx = '1.0'
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = [
|
||||
'sphinxcontrib.openapi',
|
||||
]
|
||||
|
||||
# Prefix document path to section labels, otherwise autogenerated labels would look like 'heading'
|
||||
# rather than 'path/to/file:heading'
|
||||
autosectionlabel_prefix_document = True
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
|
||||
# The suffix(es) of source filenames.
|
||||
# You can specify multiple suffix as a list of string:
|
||||
#
|
||||
source_suffix = ['.rst']
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = 'index'
|
||||
|
||||
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||
# for a list of supported languages.
|
||||
#
|
||||
# This is also used if you do content translation via gettext catalogs.
|
||||
# Usually you set "language" from the command line for these cases.
|
||||
language = None
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
# This pattern also affects html_static_path and html_extra_path.
|
||||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use.
|
||||
pygments_style = None
|
||||
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
#
|
||||
html_theme = 'sphinx_book_theme'
|
||||
|
||||
# html_theme_path = []
|
||||
|
||||
html_logo = "https://logos.openedx.org/open-edx-logo-color.png"
|
||||
html_favicon = "https://logos.openedx.org/open-edx-favicon.ico"
|
||||
|
||||
# Theme options are theme-specific and customize the look and feel of a theme
|
||||
# further. For a list of options available for each theme, see the
|
||||
# documentation.
|
||||
#
|
||||
html_theme_options = {
|
||||
"repository_url": "https://github.com/openedx/edx-platform",
|
||||
"repository_branch": "master",
|
||||
"path_to_docs": "docs/api",
|
||||
"home_page_in_toc": True,
|
||||
"use_repository_button": True,
|
||||
"use_issues_button": True,
|
||||
"use_edit_page_button": True,
|
||||
"navigation_depth": 3,
|
||||
# Please don't change unless you know what you're doing.
|
||||
"extra_footer": """
|
||||
<a rel="license" href="https://creativecommons.org/licenses/by-sa/4.0/">
|
||||
<img
|
||||
alt="Creative Commons License"
|
||||
style="border-width:0"
|
||||
src="https://i.creativecommons.org/l/by-sa/4.0/80x15.png"/>
|
||||
</a>
|
||||
<br>
|
||||
These works by
|
||||
<a
|
||||
xmlns:cc="https://creativecommons.org/ns#"
|
||||
href="https://openedx.org"
|
||||
property="cc:attributionName"
|
||||
rel="cc:attributionURL"
|
||||
>Axim Collaborative, Inc</a>
|
||||
are licensed under a
|
||||
<a
|
||||
rel="license"
|
||||
href="https://creativecommons.org/licenses/by-sa/4.0/"
|
||||
>Creative Commons Attribution-ShareAlike 4.0 International License</a>.
|
||||
"""
|
||||
}
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
html_static_path = ['_static']
|
||||
|
||||
# Custom sidebar templates, must be a dictionary that maps document names
|
||||
# to template names.
|
||||
#
|
||||
# The default sidebars (for documents that don't match any pattern) are
|
||||
# defined by theme itself. Builtin themes are using these templates by
|
||||
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
|
||||
# 'searchbox.html']``.
|
||||
#
|
||||
# html_sidebars = {}
|
||||
|
||||
|
||||
# -- Options for HTMLHelp output ---------------------------------------------
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = 'api-docsdoc'
|
||||
|
||||
|
||||
# -- Options for LaTeX output ------------------------------------------------
|
||||
|
||||
latex_elements = {
|
||||
# The paper size ('letterpaper' or 'a4paper').
|
||||
#
|
||||
# 'papersize': 'letterpaper',
|
||||
|
||||
# The font size ('10pt', '11pt' or '12pt').
|
||||
#
|
||||
# 'pointsize': '10pt',
|
||||
|
||||
# Additional stuff for the LaTeX preamble.
|
||||
#
|
||||
# 'preamble': '',
|
||||
|
||||
# Latex figure (float) alignment
|
||||
#
|
||||
# 'figure_align': 'htbp',
|
||||
}
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title,
|
||||
# author, documentclass [howto, manual, or own class]).
|
||||
latex_documents = [
|
||||
(master_doc, 'api-docs.tex', 'api-docs Documentation',
|
||||
'Nobody', 'manual'),
|
||||
]
|
||||
|
||||
|
||||
# -- Options for manual page output ------------------------------------------
|
||||
|
||||
# One entry per manual page. List of tuples
|
||||
# (source start file, name, description, authors, manual section).
|
||||
man_pages = [
|
||||
(master_doc, 'api-docs', 'api-docs Documentation',
|
||||
[author], 1)
|
||||
]
|
||||
|
||||
|
||||
# -- Options for Texinfo output ----------------------------------------------
|
||||
|
||||
# Grouping the document tree into Texinfo files. List of tuples
|
||||
# (source start file, target name, title, author,
|
||||
# dir menu entry, description, category)
|
||||
texinfo_documents = [
|
||||
(master_doc, 'api-docs', 'api-docs Documentation',
|
||||
author, 'api-docs', 'One line description of project.',
|
||||
'Miscellaneous'),
|
||||
]
|
||||
|
||||
|
||||
# -- Options for Epub output -------------------------------------------------
|
||||
|
||||
# Bibliographic Dublin Core info.
|
||||
epub_title = project
|
||||
|
||||
# The unique identifier of the text. This can be a ISBN number
|
||||
# or the project homepage.
|
||||
#
|
||||
# epub_identifier = ''
|
||||
|
||||
# A unique identification for the text.
|
||||
#
|
||||
# epub_uid = ''
|
||||
|
||||
# A list of files that should not be packed into the epub file.
|
||||
epub_exclude_files = ['search.html']
|
||||
@@ -1,11 +0,0 @@
|
||||
##################
|
||||
Open edX REST APIs
|
||||
##################
|
||||
|
||||
TODO: What should go here?
|
||||
|
||||
See all the endpoints at :doc:`The Endpoints <gen/index>`.
|
||||
|
||||
.. toctree::
|
||||
|
||||
gen/index
|
||||
@@ -59,6 +59,7 @@ extensions = [
|
||||
'sphinx.ext.intersphinx',
|
||||
'sphinx.ext.mathjax',
|
||||
'sphinx.ext.napoleon',
|
||||
'sphinxcontrib.openapi',
|
||||
]
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
|
||||
@@ -24,6 +24,7 @@ locations.
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
lms_apis
|
||||
guides
|
||||
docstrings/docstrings
|
||||
celery
|
||||
|
||||
7
docs/guides/lms_apis.rst
Normal file
7
docs/guides/lms_apis.rst
Normal file
@@ -0,0 +1,7 @@
|
||||
LMS APIs
|
||||
########
|
||||
|
||||
The LMS currently has the following API Endpoints.
|
||||
|
||||
|
||||
.. openapi:: ../lms-openapi.yaml
|
||||
@@ -1,126 +0,0 @@
|
||||
"""Generate ReST documents for sphinxcontrib-openapi from an OpenAPI swagger file.
|
||||
|
||||
This program reads an OpenAPI swagger file, and generates .rst files. Each
|
||||
file will render a segment of the swagger file, using sphinxcontrib-openapi.
|
||||
|
||||
An index.rst file is created listing all of the endpoints, linking to their
|
||||
detailed segment page.
|
||||
|
||||
"""
|
||||
|
||||
|
||||
import functools
|
||||
import itertools
|
||||
import os
|
||||
import os.path
|
||||
import re
|
||||
import sys
|
||||
import textwrap
|
||||
|
||||
import yaml
|
||||
|
||||
|
||||
def method_ordered_items(method_data):
|
||||
"""Yield the HTTP method items from method_data, in a canonical order."""
|
||||
for key in ['get', 'post', 'put', 'patch', 'delete', 'head', 'options']:
|
||||
if key in method_data:
|
||||
yield key, method_data[key]
|
||||
|
||||
|
||||
def rst_header(text, level, anchor=None):
|
||||
"""Create a ReST header, including a possible anchor.
|
||||
|
||||
Returns a multi-line string.
|
||||
|
||||
"""
|
||||
rst = []
|
||||
if anchor:
|
||||
rst.append(f".. _{anchor}:")
|
||||
rst.append("")
|
||||
char = " #=-"[level]
|
||||
if level == 1:
|
||||
rst.append(char * len(text))
|
||||
rst.append(text)
|
||||
rst.append(char * len(text))
|
||||
rst.append("")
|
||||
return "\n".join(rst)
|
||||
|
||||
|
||||
# Regexes that determine the segments. If one of these matches a URI, the
|
||||
# matched text is the segment for that endpoint.
|
||||
SEGMENTERS = [
|
||||
r"^.*?/v\d+/[\w_-]+",
|
||||
r"^(/[\w_-]+){,3}",
|
||||
]
|
||||
|
||||
|
||||
def segment_for_uri(uri):
|
||||
"""Determine the segment for an endpoint's URI."""
|
||||
for segmenter in SEGMENTERS:
|
||||
m = re.search(segmenter, uri)
|
||||
if m:
|
||||
return m.group()
|
||||
|
||||
return "default"
|
||||
|
||||
|
||||
def convert_swagger_to_sphinx(swagger_file, output_dir):
|
||||
"""Convert a swagger.yaml file to a series of Sphinx documents.
|
||||
|
||||
Args:
|
||||
swagger_file: the filename of the OpenAPI swagger file to read.
|
||||
output_dir: the directory where the .rst files should be written.
|
||||
|
||||
"""
|
||||
with open(swagger_file) as swyaml:
|
||||
swagger = yaml.safe_load(swyaml)
|
||||
|
||||
if not os.path.exists(output_dir):
|
||||
os.makedirs(output_dir)
|
||||
|
||||
rel_swagger_path = os.path.relpath(swagger_file, output_dir)
|
||||
|
||||
with open(os.path.join(output_dir, 'index.rst'), 'w') as index:
|
||||
pr_index = functools.partial(print, file=index)
|
||||
pr_index(rst_header(swagger['info']['title'], level=1))
|
||||
pr_index(swagger['info']['description'])
|
||||
pr_index(textwrap.dedent("""\
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:hidden:
|
||||
|
||||
*
|
||||
"""))
|
||||
|
||||
segment = None
|
||||
|
||||
uris = sorted(swagger['paths'])
|
||||
for segment, segment_uris in itertools.groupby(uris, key=segment_for_uri):
|
||||
|
||||
outfile = segment.strip('/').replace('/', '_')
|
||||
with open(os.path.join(output_dir, outfile + '.rst'), 'w') as outf:
|
||||
pr_outf = functools.partial(print, file=outf)
|
||||
pr_outf(rst_header(segment, level=1, anchor="gen_" + outfile))
|
||||
pr_outf(f".. openapi:: {rel_swagger_path}")
|
||||
pr_outf(" :format: markdown")
|
||||
pr_outf(" :include:")
|
||||
pr_outf(f" {segment}.*")
|
||||
|
||||
pr_index(rst_header(segment, level=2))
|
||||
|
||||
for uri in segment_uris:
|
||||
methods = swagger['paths'][uri]
|
||||
for method, op_data in method_ordered_items(methods):
|
||||
summary = ''
|
||||
if 'summary' in op_data:
|
||||
summary = " --- {}".format(op_data['summary'])
|
||||
pr_index(f":ref:`{method.upper()} {uri}<gen_{outfile}>`{summary}\n")
|
||||
|
||||
|
||||
def main(args):
|
||||
convert_swagger_to_sphinx(swagger_file=args[0], output_dir=args[1])
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main(sys.argv[1:])
|
||||
Reference in New Issue
Block a user