Add documentation

Author: virtuald

.github/workflows/dist.yml

@@ -10,23 +10,23 @@ jobs:
     - uses: actions/checkout@v2
     - uses: psf/black@stable
 
-  # check-doc:
-  #   runs-on: ubuntu-18.04
+  check-doc:
+    runs-on: ubuntu-18.04
 
-  #   steps:
-  #   - uses: actions/checkout@v2
-  #     with:
-  #       submodules: recursive
-  #       fetch-depth: 0
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        submodules: recursive
+        fetch-depth: 0
 
-  #   - uses: actions/setup-python@v2
-  #     with:
-  #       python-version: 3.8
-  #   - name: Sphinx
-  #     run: |
-  #       pip --disable-pip-version-check install -e .
-  #       pip --disable-pip-version-check install -r docs/requirements.txt
-  #       cd docs && make clean html SPHINXOPTS="-W --keep-going"
+    - uses: actions/setup-python@v2
+      with:
+        python-version: 3.8
+    - name: Sphinx
+      run: |
+        pip --disable-pip-version-check install -e .
+        pip --disable-pip-version-check install -r docs/requirements.txt
+        cd docs && make clean html SPHINXOPTS="-W --keep-going"
   
   test:
     runs-on: ${{ matrix.os }}
@@ -71,8 +71,7 @@ jobs:
 
   publish:
     runs-on: ubuntu-latest
-    #needs: [check, check-doc, test]
-    needs: [check, test]
+    needs: [check, check-doc, test]
     if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags')
 
     steps:

README.md

@@ -41,7 +41,7 @@ There are two APIs available:
 Documentation
 -------------
 
-TODO: documentation site
+Documentation can be found at https://cxxheaderparser.readthedocs.io
 
 Install
 -------

cxxheaderparser/errors.py

@@ -1,7 +1,6 @@
 import typing
 
-if typing.TYPE_CHECKING:
-    from .lexer import LexToken
+from .lexer import LexToken
 
 
 class CxxParseError(Exception):

cxxheaderparser/lexer.py

@@ -4,8 +4,6 @@
 import typing
 import sys
 
-
-from .errors import CxxParseError
 from ._ply import lex
 
 
@@ -340,6 +338,8 @@ def get_doxygen(self) -> typing.Optional[str]:
     _discard_types = {"NEWLINE", "COMMENT_SINGLELINE", "COMMENT_MULTILINE"}
 
     def _token_limit_exceeded(self):
+        from .errors import CxxParseError
+
         raise CxxParseError("no more tokens left in this group")
 
     @contextlib.contextmanager

cxxheaderparser/simple.py

@@ -7,6 +7,21 @@
 cxxheaderparser's unit tests predominantly use the simple API for parsing,
 so you can expect it to be pretty stable.
 
+The :func:`parse_string` and :func:`parse_file` functions are a great place
+to start:
+
+.. code-block:: python
+
+    from cxxheaderparser.simple import parse_string
+
+    content = '''
+        int x;
+    '''
+
+    parsed_data = parse_string(content)
+
+See below for the contents of the returned :class:`ParsedData`.
+
 """
 
 import inspect
@@ -46,7 +61,11 @@
 
 @dataclass
 class ClassScope:
+    """
+    Contains all data collected for a single C++ class
+    """
 
+    #: Information about the class declaration is here
     class_decl: ClassDecl
 
     #: Nested classes
@@ -64,6 +83,10 @@ class ClassScope:
 
 @dataclass
 class NamespaceScope:
+    """
+    Contains all data collected for a single namespace. Content for child
+    namespaces are found in the ``namespaces`` attribute.
+    """
 
     name: str = ""
 
@@ -108,11 +131,38 @@ class UsingNamespace:
 
 @dataclass
 class ParsedData:
+    """
+    Container for information parsed by the :func:`parse_file` and
+    :func:`parse_string` functions.
 
+    .. warning:: Names are not resolved, so items are stored in the scope that
+                 they are found. For example:
+
+                 .. code-block:: c++
+
+                    namespace N {
+                        class C;
+                    }
+
+                    class N::C {
+                        void fn();
+                    };
+
+                 The 'C' class would be a forward declaration in the 'N' namespace,
+                 but the ClassDecl for 'C' would be stored in the global
+                 namespace instead of the 'N' namespace.
+    """
+
+    #: Global namespace
     namespace: NamespaceScope = field(default_factory=lambda: NamespaceScope())
 
+    #: Any ``#define`` preprocessor directives encountered
     defines: typing.List[Define] = field(default_factory=list)
+
+    #: Any ``#pragma`` directives encountered
     pragmas: typing.List[Pragma] = field(default_factory=list)
+
+    #: Any ``#include`` directives encountered
     includes: typing.List[Include] = field(default_factory=list)
 
 
@@ -126,22 +176,8 @@ class SimpleCxxVisitor:
     A simple visitor that stores all of the C++ elements passed to it
     in an "easy" to use data structure
 
-    .. warning:: Names are not resolved, so items are stored in the scope that
-                 they are found. For example:
-
-                 .. code-block:: c++
-
-                    namespace N {
-                        class C;
-                    }
-
-                    class N::C {
-                        void fn();
-                    };
-
-                The 'C' class would be a forward declaration in the 'N' namespace,
-                but the ClassDecl for 'C' would be stored in the global
-                namespace instead of the 'N' namespace.
+    You probably don't want to use this directly, use :func:`parse_file`
+    or  :func:`parse_string` instead.
     """
 
     data: ParsedData

cxxheaderparser/types.py

@@ -202,7 +202,7 @@ class TemplateSpecialization:
     """
     Contains the arguments of a template specialization
 
-    .. code-block:: c++s
+    .. code-block:: c++
 
         Foo<int, Bar...>
             ~~~~~~~~~~~

docs/.gitignore

@@ -0,0 +1 @@
+/_build

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+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)

docs/conf.py

@@ -0,0 +1,64 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+import os
+import pkg_resources
+
+# -- Project information -----------------------------------------------------
+
+project = "cxxheaderparser"
+copyright = "2020-2021, Dustin Spicuzza"
+author = "Dustin Spicuzza"
+
+# The full version, including alpha/beta/rc tags
+release = pkg_resources.get_distribution("cxxheaderparser").version
+
+# -- RTD configuration ------------------------------------------------
+
+# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
+on_rtd = os.environ.get("READTHEDOCS", None) == "True"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx_autodoc_typehints",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# 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"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    import sphinx_rtd_theme
+
+    html_theme = "sphinx_rtd_theme"
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+else:
+    html_theme = "default"
+
+# 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"]
+
+always_document_param_types = True

docs/custom.rst

@@ -0,0 +1,37 @@
+Custom parsing
+==============
+
+For many users, the data provided by the simple API is enough. In some advanced
+cases you may find it necessary to use this more customizable parsing mechanism.
+
+First, define a visitor that implements the :class:`CxxVisitor` protocol. Then
+you can create an instance of it and pass it to the :class:`CxxParser`.
+
+.. code-block:: python
+
+    visitor = MyVisitor()
+    parser = CxxParser(filename, content, visitor)
+    parser.parse()
+
+    # do something with the data collected by the visitor
+
+Your visitor should do something with the data as the various callbacks are
+called. See the :class:`SimpleCxxVisitor` for inspiration.
+
+API
+---
+
+.. automodule:: cxxheaderparser.parser
+   :members:
+   :undoc-members:
+
+.. automodule:: cxxheaderparser.visitor
+   :members:
+   :undoc-members:
+
+Parser state 
+------------
+
+.. automodule:: cxxheaderparser.parserstate
+   :members:
+   :undoc-members:

docs/index.rst

@@ -0,0 +1,37 @@
+.. cxxheaderparser documentation master file, created by
+   sphinx-quickstart on Thu Dec 31 00:46:02 2020.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+cxxheaderparser
+===============
+
+A pure python C++ header parser that parses C++ headers in a mildly naive
+manner that allows it to handle many C++ constructs, including many modern
+(C++11 and beyond) features.
+
+.. warning:: cxxheaderparser intentionally does not have a C preprocessor
+             implementation! If you are parsing code with macros in it, use
+             a conforming preprocessor like the pure python preprocessor
+             `pcpp`_ or your favorite C++ compiler.
+
+.. _pcpp: https://github.com/ned14/pcpp
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   tools
+   simple
+   custom
+   types
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+