From 1399138b7bf47aecd501322c82be206714c8a11f Mon Sep 17 00:00:00 2001 From: Ilya Etingof Date: Thu, 26 Oct 2017 13:34:20 +0200 Subject: fixes to Sphinx docs layout --- docs/source/.static/favicon.ico | Bin 0 -> 4030 bytes docs/source/.static/logo.svg | 95 ++++++++++++++++++++++++++++++++++++++++ docs/source/conf.py | 38 ++++++++-------- docs/source/contents.rst | 75 ++++++++++--------------------- docs/source/download.rst | 27 ++++++++++++ docs/source/pyasn1/contents.rst | 26 +++++++++++ 6 files changed, 189 insertions(+), 72 deletions(-) create mode 100644 docs/source/.static/favicon.ico create mode 100644 docs/source/.static/logo.svg create mode 100644 docs/source/download.rst (limited to 'docs') diff --git a/docs/source/.static/favicon.ico b/docs/source/.static/favicon.ico new file mode 100644 index 0000000..87528bb Binary files /dev/null and b/docs/source/.static/favicon.ico differ diff --git a/docs/source/.static/logo.svg b/docs/source/.static/logo.svg new file mode 100644 index 0000000..e6062aa --- /dev/null +++ b/docs/source/.static/logo.svg @@ -0,0 +1,95 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/source/conf.py b/docs/source/conf.py index 20b4443..80e16b9 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -12,8 +12,6 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import os - # 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. @@ -30,9 +28,7 @@ import os extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.napoleon', - 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', - 'sphinx.ext.todo' ] # Add any paths that contain templates here, relative to this directory. @@ -50,8 +46,7 @@ source_suffix = '.rst' master_doc = 'contents' # General information about the project. -project = u'PyASN1' -# noinspection PyShadowingBuiltins +project = u'ASN.1 types and codecs' copyright = u'2005-2017, Ilya Etingof ' author = u'Ilya Etingof ' @@ -60,9 +55,9 @@ author = u'Ilya Etingof ' # built documents. # # The short X.Y version. -version = '0.3' +version = '0.4' # The full version, including alpha/beta/rc tags. -release = '0.3.1' +release = '0.4' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -106,7 +101,7 @@ pygments_style = 'sphinx' # keep_warnings = False # If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = True +todo_include_todos = False # -- Options for HTML output ---------------------------------------------- @@ -118,20 +113,30 @@ html_theme = 'alabaster' # further. For a list of options available for each theme, see the # documentation. html_theme_options = { - 'description': 'ASN.1 types and codecs', + 'logo': 'logo.svg', + 'description': '

Brought by SNMP Labs

', 'show_powered_by': False, 'github_user': 'etingof', 'github_repo': 'pyasn1', 'fixed_sidebar': True, } +html_sidebars = { + '**': [ + 'about.html', + 'navigation.html', + 'relations.html', + 'searchbox.html', + 'donate.html', + ] +} + # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". # html_title = None -html_title = "PyASN1" # A shorter title for the navigation bar. Default is the same as html_title. # html_short_title = None @@ -143,17 +148,12 @@ html_title = "PyASN1" # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. -# html_favicon = None +html_favicon = '.static/favicon.ico' # 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". -# if 'PYASN1DEV' in os.environ: -# html_static_path = ['.static'] -# -# # Custom CSS theme -# if 'PYASN1DEV' in os.environ: -# html_style = 'css/rtdimproved.css' +html_static_path = ['.static'] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied @@ -324,5 +324,3 @@ napoleon_use_admonition_for_references = False napoleon_use_ivar = False napoleon_use_param = False napoleon_use_rtype = False - -# Alabaster theme \ No newline at end of file diff --git a/docs/source/contents.rst b/docs/source/contents.rst index f2955a1..c4582bd 100644 --- a/docs/source/contents.rst +++ b/docs/source/contents.rst @@ -3,7 +3,7 @@ ASN.1 library for Python ======================== .. toctree:: - :maxdepth: 3 + :maxdepth: 1 Abstract Syntax Notation One (`ASN.1 `_) is a @@ -82,68 +82,29 @@ and oftentimes fell victim to its edge cases. On the bright side, ASN.1 has been around for a long time, it is well understood and security reviewed. -Library documentation ---------------------- - -As of this moment, pyasn1 library implements all ASN.1 data -types as Python objects in accordance with X.208 standard. Later, -post-1995, revision (X.680) introduced some changes to the schema -language which may not be fully supported by pyasn1. Aside from data -types a collection of data transformation codecs comes with pyasn1 package. - -As for ASN.1 schema language, pyasn1 package does -not ship any compiler for it. However, there's a tool called -`asn1late `_ which is an ASN.1 -grammar parser paired to code generator capable of generating pyasn1 -code. So this is an alternative (or at least a good start) to manual -implementation of pyasn1 classes from ASN.1 specification. - -Both `pyasn1 `_ and -`pyasn1-modules `_ libraries -can be used out-of-the-box with Python versions 2.4 through 3.6. -No external dependencies required. +Documentation +------------- .. toctree:: - :maxdepth: 3 + :maxdepth: 2 /pyasn1/contents Use case -------- - .. toctree:: - :maxdepth: 3 +.. toctree:: + :maxdepth: 2 - /example-use-case + /example-use-case Download & Install ------------------ -The PyASN1 software is provided under terms and conditions of BSD-style -:ref:`license`, and can be freely downloaded from `Github `_ -or `PyPI `_. - -It is pure-Python and has no dependencies. Considering how much industrial or finance -software can be stuck with an old platform (think RHEL 5), we struggle to maintain its -compatibility back to the very pre-historic Python (which is 2.4!). - -The best way to obtain PyASN1 is by running `pip`: - -.. code-block:: bash - - $ pip install pyasn1 - -or - -.. code-block:: bash - - $ easy_install pyasn1 - -You may also want to use `pyasn1-modules`: - -.. code-block:: bash +.. toctree:: + :maxdepth: 2 - $ pip install pyasn1-modules + /download Changes ------- @@ -152,10 +113,20 @@ All changes and release history is maintained in changelog. There you could also download the latest unreleased pyasn1 tarball containing the latest fixes and improvements. - .. toctree:: - :maxdepth: 1 +.. toctree:: + :maxdepth: 1 + + /changelog + +License +------- + +The PyASN1 software is distributed under 2-clause BSD License. + +.. toctree:: + :maxdepth: 2 - /changelog + /license Getting help ------------ diff --git a/docs/source/download.rst b/docs/source/download.rst new file mode 100644 index 0000000..cf78126 --- /dev/null +++ b/docs/source/download.rst @@ -0,0 +1,27 @@ + +Download & Install +================== + +The *pyasn1* library is a pure-Python package with no external +dependencies. Considering how much industrial or finance software +can be stuck with an old platform (think RHEL 5), we struggle to +maintain its compatibility back to the very pre-historic Python +(which is 2.4!). + +The best way to obtain PyASN1 is by running `pip`: + +.. code-block:: bash + + $ virtualenv venv + $ source venv/bin/activate + $ pip install pyasn1 + +You may also want to use `pyasn1-modules`: + +.. code-block:: bash + + $ pip install pyasn1-modules + +Alternatively, you can download the latest release from +`GitHub `_ +or `PyPI `_. diff --git a/docs/source/pyasn1/contents.rst b/docs/source/pyasn1/contents.rst index 1dc9e58..57ba4b2 100644 --- a/docs/source/pyasn1/contents.rst +++ b/docs/source/pyasn1/contents.rst @@ -1,6 +1,30 @@ .. _pyasn1: +Library documentation +===================== + +As of this moment, pyasn1 library implements all ASN.1 data +types as Python objects in accordance with X.208 standard. Later, +post-1995, revision (X.680) introduced some changes to the schema +language which may not be fully supported by pyasn1. Aside from data +types a collection of data transformation codecs comes with the +pyasn1 package. + +As for ASN.1 schema language, pyasn1 package does +not ship any compiler for it. However, there's a tool called +`asn1late `_ which is an ASN.1 +grammar parser paired to code generator capable of generating pyasn1 +code. So this is an alternative (or at least a good start) to manual +implementation of pyasn1 classes from ASN.1 specification. + +Both `pyasn1 `_ and +`pyasn1-modules `_ libraries +can be used out-of-the-box with Python versions 2.4 through 3.6. +No external dependencies required. + +.. _pyasn1-types: + ASN.1 types ----------- @@ -136,6 +160,8 @@ its :ref:`fields ` specification. /pyasn1/type/opentype/contents /pyasn1/type/namedval/contents +.. _pyasn1-codecs: + Serialisation codecs -------------------- -- cgit v1.2.1