From 96b7cd78b88be673d291515f01a3007fc414285a Mon Sep 17 00:00:00 2001 From: Anthony Shaw Date: Thu, 4 Mar 2021 11:16:32 +1100 Subject: [PATCH 1/2] Refactor docs into a different theme, improve nav --- .gitignore | 3 +- docs/conf.py | 68 +++++++++++++++++++++++++------------------ docs/index.rst | 58 ++++++++++++++---------------------- docs/requirements.txt | 1 + 4 files changed, 65 insertions(+), 65 deletions(-) create mode 100644 docs/requirements.txt diff --git a/.gitignore b/.gitignore index ff05e560..e776c10e 100644 --- a/.gitignore +++ b/.gitignore @@ -45,7 +45,8 @@ src/build # Virtual Environments /env* - +.venv/ +docs/_build/ # Visual Studio Files /.vs/* /tests/.vs/* diff --git a/docs/conf.py b/docs/conf.py index 251cf948..55fcbaac 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -14,17 +14,20 @@ # import os import sys -sys.path.insert(0, os.path.abspath('..')) +from datetime import date + +sys.path.insert(0, os.path.abspath("..")) # -- Project information ----------------------------------------------------- -project = u'MSAL Python' -copyright = u'2018, Microsoft' -author = u'Microsoft' +project = u"MSAL Python" +copyright = u"{0}, Microsoft".format(date.today().year) +author = u"Microsoft" # The short X.Y version from msal import __version__ as version + # The full version, including alpha/beta/rc tags release = version @@ -39,21 +42,21 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.githubpages', + "sphinx.ext.autodoc", + "sphinx.ext.githubpages", ] # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ["_templates"] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # # source_suffix = ['.rst', '.md'] -source_suffix = '.rst' +source_suffix = ".rst" # The master toctree document. -master_doc = 'index' +master_doc = "index" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -65,7 +68,7 @@ # 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 = [u'_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = [u"_build", "Thumbs.db", ".DS_Store"] # The name of the Pygments (syntax highlighting) style to use. pygments_style = None @@ -76,19 +79,23 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -# html_theme = 'alabaster' -html_theme = 'sphinx_rtd_theme' +html_theme = "furo" # 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 = {} +html_theme_options = { + "light_css_variables": { + "font-stack": "'Segoe UI', SegoeUI, 'Helvetica Neue', Helvetica, Arial, sans-serif", + "font-stack--monospace": "SFMono-Regular, Consolas, 'Liberation Mono', Menlo, Courier, monospace", + }, +} # 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'] +html_static_path = ["_static"] # Custom sidebar templates, must be a dictionary that maps document names # to template names. @@ -104,7 +111,7 @@ # -- Options for HTMLHelp output --------------------------------------------- # Output file base name for HTML help builder. -htmlhelp_basename = 'MSALPythondoc' +htmlhelp_basename = "MSALPythondoc" # -- Options for LaTeX output ------------------------------------------------ @@ -113,15 +120,12 @@ # 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', @@ -131,8 +135,13 @@ # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'MSALPython.tex', u'MSAL Python Documentation', - u'Microsoft', 'manual'), + ( + master_doc, + "MSALPython.tex", + u"MSAL Python Documentation", + u"Microsoft", + "manual", + ), ] @@ -140,10 +149,7 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'msalpython', u'MSAL Python Documentation', - [author], 1) -] +man_pages = [(master_doc, "msalpython", u"MSAL Python Documentation", [author], 1)] # -- Options for Texinfo output ---------------------------------------------- @@ -152,9 +158,15 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'MSALPython', u'MSAL Python Documentation', - author, 'MSALPython', 'One line description of project.', - 'Miscellaneous'), + ( + master_doc, + "MSALPython", + u"MSAL Python Documentation", + author, + "MSALPython", + "One line description of project.", + "Miscellaneous", + ), ] @@ -173,7 +185,7 @@ # epub_uid = '' # A list of files that should not be packed into the epub file. -epub_exclude_files = ['search.html'] +epub_exclude_files = ["search.html"] # -- Extension configuration ------------------------------------------------- diff --git a/docs/index.rst b/docs/index.rst index baad12fd..c70428b4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,17 +1,13 @@ -.. MSAL Python documentation master file, created by - sphinx-quickstart on Tue Dec 18 10:53:22 2018. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -.. This file is also inspired by - https://pythonhosted.org/an_example_pypi_project/sphinx.html#full-code-example - -Welcome to MSAL Python's documentation! -======================================= +MSAL Python documentation +========================= .. toctree:: :maxdepth: 2 :caption: Contents: + :hidden: + + MSAL Documentation + GitHub Repository You can find high level conceptual documentations in the project `README `_ @@ -22,9 +18,8 @@ and The documentation hosted here is for API Reference. - -PublicClientApplication and ConfidentialClientApplication -========================================================= +API +=== MSAL proposes a clean separation between `public client applications and confidential client applications @@ -33,33 +28,32 @@ MSAL proposes a clean separation between They are implemented as two separated classes, with different methods for different authentication scenarios. -PublicClientApplication +ClientApplication ----------------------- -.. autoclass:: msal.PublicClientApplication - :members: -ConfidentialClientApplication ------------------------------ -.. autoclass:: msal.ConfidentialClientApplication +.. autoclass:: msal.ClientApplication :members: + :inherited-members: -Shared Methods --------------- -Both PublicClientApplication and ConfidentialClientApplication -have following methods inherited from their base class. -You typically do not need to initiate this base class, though. +PublicClientApplication +----------------------- -.. autoclass:: msal.ClientApplication +.. autoclass:: msal.PublicClientApplication :members: + :inherited-members: - .. automethod:: __init__ +ConfidentialClientApplication +----------------------------- +.. autoclass:: msal.ConfidentialClientApplication + :members: + :inherited-members: TokenCache -========== +---------- -One of the parameter accepted by +One of the parameters accepted by both `PublicClientApplication` and `ConfidentialClientApplication` is the `TokenCache`. @@ -71,11 +65,3 @@ See `SerializableTokenCache` for example. .. autoclass:: msal.SerializableTokenCache :members: - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`search` - diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..9e279e79 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +furo \ No newline at end of file From 3a3cdb6f7ca44ebcd5dcf064a7972359e0d22d67 Mon Sep 17 00:00:00 2001 From: Anthony Shaw Date: Thu, 4 Mar 2021 13:31:47 +1100 Subject: [PATCH 2/2] Amendments to PR --- docs/conf.py | 72 ++++++++++++++++++++----------------------- docs/index.rst | 8 ----- docs/requirements.txt | 3 +- 3 files changed, 35 insertions(+), 48 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 55fcbaac..810dfc02 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,22 +12,20 @@ # 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. # +from datetime import date import os import sys -from datetime import date - -sys.path.insert(0, os.path.abspath("..")) +sys.path.insert(0, os.path.abspath('..')) # -- Project information ----------------------------------------------------- -project = u"MSAL Python" -copyright = u"{0}, Microsoft".format(date.today().year) -author = u"Microsoft" +project = u'MSAL Python' +copyright = u'{0}, Microsoft'.format(date.today().year) +author = u'Microsoft' # The short X.Y version from msal import __version__ as version - # The full version, including alpha/beta/rc tags release = version @@ -42,21 +40,21 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - "sphinx.ext.autodoc", - "sphinx.ext.githubpages", + 'sphinx.ext.autodoc', + 'sphinx.ext.githubpages', ] # Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] +templates_path = ['_templates'] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # # source_suffix = ['.rst', '.md'] -source_suffix = ".rst" +source_suffix = '.rst' # The master toctree document. -master_doc = "index" +master_doc = 'index' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -68,7 +66,7 @@ # 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 = [u"_build", "Thumbs.db", ".DS_Store"] +exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store'] # The name of the Pygments (syntax highlighting) style to use. pygments_style = None @@ -79,23 +77,24 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = "furo" +# html_theme = 'alabaster' +html_theme = 'furo' # 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 = { - "light_css_variables": { - "font-stack": "'Segoe UI', SegoeUI, 'Helvetica Neue', Helvetica, Arial, sans-serif", - "font-stack--monospace": "SFMono-Regular, Consolas, 'Liberation Mono', Menlo, Courier, monospace", - }, + "light_css_variables": { + "font-stack": "'Segoe UI', SegoeUI, 'Helvetica Neue', Helvetica, Arial, sans-serif", + "font-stack--monospace": "SFMono-Regular, Consolas, 'Liberation Mono', Menlo, Courier, monospace", + }, } # 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"] +html_static_path = ['_static'] # Custom sidebar templates, must be a dictionary that maps document names # to template names. @@ -111,7 +110,7 @@ # -- Options for HTMLHelp output --------------------------------------------- # Output file base name for HTML help builder. -htmlhelp_basename = "MSALPythondoc" +htmlhelp_basename = 'MSALPythondoc' # -- Options for LaTeX output ------------------------------------------------ @@ -120,12 +119,15 @@ # 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', @@ -135,13 +137,8 @@ # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - ( - master_doc, - "MSALPython.tex", - u"MSAL Python Documentation", - u"Microsoft", - "manual", - ), + (master_doc, 'MSALPython.tex', u'MSAL Python Documentation', + u'Microsoft', 'manual'), ] @@ -149,7 +146,10 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [(master_doc, "msalpython", u"MSAL Python Documentation", [author], 1)] +man_pages = [ + (master_doc, 'msalpython', u'MSAL Python Documentation', + [author], 1) +] # -- Options for Texinfo output ---------------------------------------------- @@ -158,15 +158,9 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - ( - master_doc, - "MSALPython", - u"MSAL Python Documentation", - author, - "MSALPython", - "One line description of project.", - "Miscellaneous", - ), + (master_doc, 'MSALPython', u'MSAL Python Documentation', + author, 'MSALPython', 'One line description of project.', + 'Miscellaneous'), ] @@ -185,7 +179,7 @@ # epub_uid = '' # A list of files that should not be packed into the epub file. -epub_exclude_files = ["search.html"] +epub_exclude_files = ['search.html'] -# -- Extension configuration ------------------------------------------------- +# -- Extension configuration ------------------------------------------------- \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index c70428b4..439ca0ee 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -28,14 +28,6 @@ MSAL proposes a clean separation between They are implemented as two separated classes, with different methods for different authentication scenarios. -ClientApplication ------------------------ - -.. autoclass:: msal.ClientApplication - :members: - :inherited-members: - - PublicClientApplication ----------------------- diff --git a/docs/requirements.txt b/docs/requirements.txt index 9e279e79..d5de57fe 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1 +1,2 @@ -furo \ No newline at end of file +furo +-r ../requirements.txt \ No newline at end of file