diff --git a/Makefile b/Makefile index 8a0a6840f417..e075f092f158 100644 --- a/Makefile +++ b/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 diff --git a/docs/api/.gitignore b/docs/api/.gitignore deleted file mode 100644 index 2b81fd4a0ebe..000000000000 --- a/docs/api/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -_build -gen diff --git a/docs/api/Makefile b/docs/api/Makefile deleted file mode 100644 index 8fe8f3c739f6..000000000000 --- a/docs/api/Makefile +++ /dev/null @@ -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) diff --git a/docs/api/__init__.py b/docs/api/__init__.py deleted file mode 100644 index e69de29bb2d1..000000000000 diff --git a/docs/api/conf.py b/docs/api/conf.py deleted file mode 100644 index b0f6a436f3cb..000000000000 --- a/docs/api/conf.py +++ /dev/null @@ -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": """ - - Creative Commons License - -
- These works by - Axim Collaborative, Inc - are licensed under a - Creative Commons Attribution-ShareAlike 4.0 International License. - """ -} - -# 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'] diff --git a/docs/api/index.rst b/docs/api/index.rst deleted file mode 100644 index be37b66d5256..000000000000 --- a/docs/api/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -################## -Open edX REST APIs -################## - -TODO: What should go here? - -See all the endpoints at :doc:`The Endpoints `. - -.. toctree:: - - gen/index diff --git a/docs/guides/conf.py b/docs/guides/conf.py index 64b38a283ad4..f0491d55981a 100644 --- a/docs/guides/conf.py +++ b/docs/guides/conf.py @@ -59,6 +59,7 @@ 'sphinx.ext.intersphinx', 'sphinx.ext.mathjax', 'sphinx.ext.napoleon', + 'sphinxcontrib.openapi', ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/guides/index.rst b/docs/guides/index.rst index 0946a37c3848..371fce5586b4 100644 --- a/docs/guides/index.rst +++ b/docs/guides/index.rst @@ -24,6 +24,7 @@ locations. .. toctree:: :maxdepth: 2 + lms_apis guides docstrings/docstrings celery diff --git a/docs/guides/lms_apis.rst b/docs/guides/lms_apis.rst new file mode 100644 index 000000000000..7c77b47e5005 --- /dev/null +++ b/docs/guides/lms_apis.rst @@ -0,0 +1,7 @@ +LMS APIs +######## + +The LMS currently has the following API Endpoints. + + +.. openapi:: ../lms-openapi.yaml diff --git a/docs/swagger.yaml b/docs/lms-openapi.yaml similarity index 100% rename from docs/swagger.yaml rename to docs/lms-openapi.yaml diff --git a/docs/sw2sphinxopenapi.py b/docs/sw2sphinxopenapi.py deleted file mode 100644 index 28f8b421c9b4..000000000000 --- a/docs/sw2sphinxopenapi.py +++ /dev/null @@ -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}`{summary}\n") - - -def main(args): - convert_swagger_to_sphinx(swagger_file=args[0], output_dir=args[1]) - - -if __name__ == '__main__': - main(sys.argv[1:])