From fccf439117016e605a8b763b3dffcd94a35506ad Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sat, 23 Feb 2013 23:08:30 +0200 Subject: [PATCH 1/7] Add missing titles to few docs to make sure they're rendered in docs. --- docs/source/doc/llvm.core.Constant.rst | 3 +++ docs/source/doc/llvm.core.GlobalVariable.rst | 3 +++ docs/source/doc/llvm.core.Module.rst | 4 +++- docs/source/doc/llvm.core.StructType.rst | 3 +++ 4 files changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/source/doc/llvm.core.Constant.rst b/docs/source/doc/llvm.core.Constant.rst index 4f2ed08..9b479c2 100644 --- a/docs/source/doc/llvm.core.Constant.rst +++ b/docs/source/doc/llvm.core.Constant.rst @@ -4,6 +4,9 @@ | title: Constant (llvm.core) | +-------------------------------+ +llvm.core.Constant +================== + ``Constant``-s represents constants that appear within the code. The values of such objects are known at creation time. Constants can be created from Python constants. A constant expression is also a constant diff --git a/docs/source/doc/llvm.core.GlobalVariable.rst b/docs/source/doc/llvm.core.GlobalVariable.rst index 392a6a0..48c8255 100644 --- a/docs/source/doc/llvm.core.GlobalVariable.rst +++ b/docs/source/doc/llvm.core.GlobalVariable.rst @@ -4,6 +4,9 @@ | title: GlobalVariable (llvm.core) | +-------------------------------------+ +llvm.core.GlobalVariable +======================== + Global variables (``llvm.core.GlobalVariable``) are subclasses of `llvm.core.GlobalValue `_ and represent module-level variables. These can have optional initializers and can be diff --git a/docs/source/doc/llvm.core.Module.rst b/docs/source/doc/llvm.core.Module.rst index 3dbd5c8..824b6cd 100644 --- a/docs/source/doc/llvm.core.Module.rst +++ b/docs/source/doc/llvm.core.Module.rst @@ -4,11 +4,13 @@ | title: Module (llvm.core) | +-----------------------------+ +llvm.core.Module +================ + Modules are top-level container objects. You need to create a module object first, before you can add global variables, aliases or functions. Modules are created using the static method ``Module.new``: - .. code-block:: python #!/usr/bin/env python diff --git a/docs/source/doc/llvm.core.StructType.rst b/docs/source/doc/llvm.core.StructType.rst index e69de29..0ac3ce6 100644 --- a/docs/source/doc/llvm.core.StructType.rst +++ b/docs/source/doc/llvm.core.StructType.rst @@ -0,0 +1,3 @@ +llvm.core.StructType +==================== + From 650a49dcab6d4b5836fa7daa62be5c3ec4b94770 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sat, 23 Feb 2013 23:13:23 +0200 Subject: [PATCH 2/7] Fix import statements. --- docs/source/doc/llvm.core.Module.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/source/doc/llvm.core.Module.rst b/docs/source/doc/llvm.core.Module.rst index 824b6cd..4052a4f 100644 --- a/docs/source/doc/llvm.core.Module.rst +++ b/docs/source/doc/llvm.core.Module.rst @@ -15,7 +15,8 @@ Modules are created using the static method ``Module.new``: #!/usr/bin/env python - from llvm import \* from llvm.core import \* + from llvm import * + from llvm.core import * # create a module my_module = Module.new('my_module') From 769376b0556cc7e2daea138723c9dfc3c2e3da1f Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 24 Feb 2013 00:03:26 +0200 Subject: [PATCH 3/7] Sublists must have blank lines before and after. --- docs/source/doc/llvm_concepts.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/doc/llvm_concepts.rst b/docs/source/doc/llvm_concepts.rst index c642994..8690e49 100644 --- a/docs/source/doc/llvm_concepts.rst +++ b/docs/source/doc/llvm_concepts.rst @@ -28,6 +28,7 @@ follow these steps: - add a *basic block* to the function - using a helper object called an *instruction builder*, add two instructions into the basic block: + - an instruction to add the two arguments and store the result into a temporary variable - a return From 8086487ab742a743d02bbb9b3b9fd2104162da77 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 24 Feb 2013 00:08:28 +0200 Subject: [PATCH 4/7] Fix "title underline too short" warnings. --- docs/source/doc/examples/JITTutorial2.rst | 2 +- docs/source/doc/kaleidoscope/PythonLangImpl1.rst | 2 +- docs/source/doc/kaleidoscope/PythonLangImpl8.rst | 10 +++++----- docs/source/doc/llvm_cbuilder.rst | 2 +- docs/source/index.rst | 2 +- 5 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/source/doc/examples/JITTutorial2.rst b/docs/source/doc/examples/JITTutorial2.rst index a9a9979..6e76150 100644 --- a/docs/source/doc/examples/JITTutorial2.rst +++ b/docs/source/doc/examples/JITTutorial2.rst @@ -1,5 +1,5 @@ A More Complicated Function -==================== +=========================== .. code-block:: python diff --git a/docs/source/doc/kaleidoscope/PythonLangImpl1.rst b/docs/source/doc/kaleidoscope/PythonLangImpl1.rst index 00b16fb..ae4b80d 100644 --- a/docs/source/doc/kaleidoscope/PythonLangImpl1.rst +++ b/docs/source/doc/kaleidoscope/PythonLangImpl1.rst @@ -6,7 +6,7 @@ Written by `Chris Lattner `_ and `Max Shawabkeh `_ Introduction -========= +============ Welcome to the "Implementing a language with LLVM" tutorial. This tutorial runs through the implementation of a simple language, showing diff --git a/docs/source/doc/kaleidoscope/PythonLangImpl8.rst b/docs/source/doc/kaleidoscope/PythonLangImpl8.rst index dd4abc1..eb13dd0 100644 --- a/docs/source/doc/kaleidoscope/PythonLangImpl8.rst +++ b/docs/source/doc/kaleidoscope/PythonLangImpl8.rst @@ -1,6 +1,6 @@ -************************************************* +*************************************************** Chapter 8: Conclusion and other useful LLVM tidbits -************************************************* +*************************************************** Written by Chris Lattner @@ -106,7 +106,7 @@ generating LLVM IR. These are some of the more subtle things that may not be obv but are very useful if you want to take advantage of LLVM's capabilities. Properties of the LLVM IR -======================== +========================= We have a couple common questions about code in the LLVM IR form - let's just get these out of the way right now, shall we? @@ -164,7 +164,7 @@ This can make sense for specialized domains such as an in-kernel language. -------------- Safety Guarantees ----------------- +----------------- Many of the languages above are also "safe" languages: it is impossible for a program written in Java to corrupt its address space and @@ -236,7 +236,7 @@ you desire in your front-end, on the language-specific AST. -------------- Tips and Tricks -============== +=============== There is a variety of useful tips and tricks that you come to know after working on/with LLVM that aren't obvious at first glance. diff --git a/docs/source/doc/llvm_cbuilder.rst b/docs/source/doc/llvm_cbuilder.rst index 990bfb0..c8623c2 100644 --- a/docs/source/doc/llvm_cbuilder.rst +++ b/docs/source/doc/llvm_cbuilder.rst @@ -1,5 +1,5 @@ llvm_cbuilder -========= +============= llvm_cbuilder is a set of Python-contexts you can use to write C-like constructs in Python which generates llvmpy code directly. diff --git a/docs/source/index.rst b/docs/source/index.rst index 9f86b32..7798b77 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -4,7 +4,7 @@ contain the root `toctree` directive. Documentation for llvmpy -================= +======================== Contents: From d74ff4dc2bebee2a7ceabaafaebc6dd5c5db8538 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 24 Feb 2013 00:22:54 +0200 Subject: [PATCH 5/7] Fill in required explicit argument for code-block. --- docs/source/doc/kaleidoscope/PythonLangImpl7.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/source/doc/kaleidoscope/PythonLangImpl7.rst b/docs/source/doc/kaleidoscope/PythonLangImpl7.rst index 629608c..7e86ee4 100644 --- a/docs/source/doc/kaleidoscope/PythonLangImpl7.rst +++ b/docs/source/doc/kaleidoscope/PythonLangImpl7.rst @@ -295,7 +295,7 @@ variables is a useful thing regardless of whether you will be mutating them. Here's a motivating example that shows how we could use these: -.. code-block:: +.. code-block:: none # Define ':' for sequencing: as a low-precedence operator that ignores operands # and just returns the RHS. @@ -352,7 +352,7 @@ function that ensures that the allocas are created in the entry block of the function: -.. code-block:: +.. code-block:: python # Creates an alloca instruction in the entry block of the function. This is used # for mutable variables. @@ -475,7 +475,7 @@ It is interesting to see what the code looks like before and after the mem2reg optimization runs. For example, this is the before/after code for our recursive fib function. Before the optimization: -.. code-block:: +.. code-block:: llvm define double @fib(double %x) { entry: @@ -515,7 +515,7 @@ still just make the PHI. Here is the code after the mem2reg pass runs: -.. code-block:: +.. code-block:: llvm define double @fib(double %x) { entry: @@ -651,7 +651,7 @@ Now that we have an assignment operator, we can mutate loop variables and arguments. For example, we can now run code like this: -.. code-block:: +.. code-block:: none # Function to print a double. extern printd(x) From d36cd1dbc7786b714da54a9cfd781f02045023c0 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 24 Feb 2013 00:40:25 +0200 Subject: [PATCH 6/7] Add docstring documentation to all llvm.core classes. Some classes have docstrings, and lack rST docs (e.g. Module), few others vice versa. It's unclear what is the best way to deal with this. IMHO, docstrings should prevail, i.e. existing docs would rather be moved to docstings. Anyway, for now just make sure that users don't miss documentation, even if it's just list of classmembers. --- docs/source/doc/llvm.core.Argument.rst | 7 +++++++ docs/source/doc/llvm.core.ArrayType.rst | 7 +++++++ docs/source/doc/llvm.core.BasicBlock.rst | 7 +++++++ docs/source/doc/llvm.core.Builder.rst | 7 +++++++ docs/source/doc/llvm.core.Constant.rst | 6 ++++++ docs/source/doc/llvm.core.Function.rst | 7 +++++++ docs/source/doc/llvm.core.FunctionType.rst | 7 +++++++ docs/source/doc/llvm.core.GlobalValue.rst | 6 ++++++ docs/source/doc/llvm.core.GlobalVariable.rst | 7 +++++++ docs/source/doc/llvm.core.Instruction.rst | 7 +++++++ docs/source/doc/llvm.core.IntegerType.rst | 7 +++++++ docs/source/doc/llvm.core.Module.rst | 7 +++++++ docs/source/doc/llvm.core.PointerType.rst | 7 +++++++ docs/source/doc/llvm.core.StructType.rst | 5 +++++ docs/source/doc/llvm.core.Type.rst | 7 +++++++ docs/source/doc/llvm.core.User.rst | 7 +++++++ docs/source/doc/llvm.core.Value.rst | 7 +++++++ docs/source/doc/llvm.core.VectorType.rst | 7 +++++++ 18 files changed, 122 insertions(+) diff --git a/docs/source/doc/llvm.core.Argument.rst b/docs/source/doc/llvm.core.Argument.rst index 2481665..a2ffbfa 100644 --- a/docs/source/doc/llvm.core.Argument.rst +++ b/docs/source/doc/llvm.core.Argument.rst @@ -56,3 +56,10 @@ Add an attribute ``attr`` to the argument, from the set listed above. ~~~~~~~~~~~~~~~~~~~~~~~~~~ Remove the attribute ``attr`` of the argument. + + +Automatically Generated Documentation +------------------------------------- +.. autoclass:: llvm.core.Argument + :members: + :undoc-members: diff --git a/docs/source/doc/llvm.core.ArrayType.rst b/docs/source/doc/llvm.core.ArrayType.rst index f8b5e0c..3a4e645 100644 --- a/docs/source/doc/llvm.core.ArrayType.rst +++ b/docs/source/doc/llvm.core.ArrayType.rst @@ -28,3 +28,10 @@ A ``Type`` object representing the type of the element of the array. [read-only] The number of elements in the array. + + +Automatically Generated Documentation +------------------------------------- +.. autoclass:: llvm.core.ArrayType + :members: + :undoc-members: diff --git a/docs/source/doc/llvm.core.BasicBlock.rst b/docs/source/doc/llvm.core.BasicBlock.rst index 74806a6..eb10be3 100644 --- a/docs/source/doc/llvm.core.BasicBlock.rst +++ b/docs/source/doc/llvm.core.BasicBlock.rst @@ -42,3 +42,10 @@ The parent function of this basicblock. ~~~~~~~~~~~~~~~~ A list of instructions in this basicblock. + + +Automatically Generated Documentation +------------------------------------- +.. autoclass:: llvm.core.BasicBlock + :members: + :undoc-members: diff --git a/docs/source/doc/llvm.core.Builder.rst b/docs/source/doc/llvm.core.Builder.rst index 1e90908..24b9361 100644 --- a/docs/source/doc/llvm.core.Builder.rst +++ b/docs/source/doc/llvm.core.Builder.rst @@ -409,3 +409,10 @@ positioned. ~~~~~~~~~ Deprecated. Same as ``basic_block`` + + +Automatically Generated Documentation +------------------------------------- +.. autoclass:: llvm.core.Builder + :members: + :undoc-members: diff --git a/docs/source/doc/llvm.core.Constant.rst b/docs/source/doc/llvm.core.Constant.rst index 9b479c2..ae67fa4 100644 --- a/docs/source/doc/llvm.core.Constant.rst +++ b/docs/source/doc/llvm.core.Constant.rst @@ -354,3 +354,9 @@ some examples: assert isinstance(k1, ConstantInt) assert isinstance(k2, ConstantArray) + +Automatically Generated Documentation +------------------------------------- +.. autoclass:: llvm.core.Constant + :members: + :undoc-members: diff --git a/docs/source/doc/llvm.core.Function.rst b/docs/source/doc/llvm.core.Function.rst index 1d6070c..cda101e 100644 --- a/docs/source/doc/llvm.core.Function.rst +++ b/docs/source/doc/llvm.core.Function.rst @@ -149,3 +149,10 @@ function bodies. Verifies the function. See `LLVM docs `_. + + +Automatically Generated Documentation +------------------------------------- +.. autoclass:: llvm.core.Function + :members: + :undoc-members: diff --git a/docs/source/doc/llvm.core.FunctionType.rst b/docs/source/doc/llvm.core.FunctionType.rst index 8d40009..7b728a8 100644 --- a/docs/source/doc/llvm.core.FunctionType.rst +++ b/docs/source/doc/llvm.core.FunctionType.rst @@ -46,3 +46,10 @@ the function. Used like this: Type.int(), Type.int() ] ) for arg in func_type.args: assert arg.kind == TYPE_INTEGER assert arg == Type.int() assert func_type.arg_count == len(func_type.args) + + +Automatically Generated Documentation +------------------------------------- +.. autoclass:: llvm.core.FunctionType + :members: + :undoc-members: diff --git a/docs/source/doc/llvm.core.GlobalValue.rst b/docs/source/doc/llvm.core.GlobalValue.rst index 70dee7b..a5c2383 100644 --- a/docs/source/doc/llvm.core.GlobalValue.rst +++ b/docs/source/doc/llvm.core.GlobalValue.rst @@ -95,3 +95,9 @@ A power-of-2 integer indicating the boundary to align to. The module object to which this global belongs to. + +Automatically Generated Documentation +------------------------------------- +.. autoclass:: llvm.core.GlobalValue + :members: + :undoc-members: diff --git a/docs/source/doc/llvm.core.GlobalVariable.rst b/docs/source/doc/llvm.core.GlobalVariable.rst index 48c8255..1ba69d8 100644 --- a/docs/source/doc/llvm.core.GlobalVariable.rst +++ b/docs/source/doc/llvm.core.GlobalVariable.rst @@ -40,3 +40,10 @@ class, or by using the static method ``GlobalVariable.new``. # list all global variables in a module for gv in module_obj.global_variables: print gv.name, "of type", gv.type + + +Automatically Generated Documentation +------------------------------------- +.. autoclass:: llvm.core.GlobalVariable + :members: + :undoc-members: diff --git a/docs/source/doc/llvm.core.Instruction.rst b/docs/source/doc/llvm.core.Instruction.rst index 95aeb81..67c43f0 100644 --- a/docs/source/doc/llvm.core.Instruction.rst +++ b/docs/source/doc/llvm.core.Instruction.rst @@ -240,3 +240,10 @@ Properties The predicate of the compare instruction, one of the ``ICMP_*`` or ``FCMP_*`` constants. + + +Automatically Generated Documentation +------------------------------------- +.. autoclass:: llvm.core.Instruction + :members: + :undoc-members: diff --git a/docs/source/doc/llvm.core.IntegerType.rst b/docs/source/doc/llvm.core.IntegerType.rst index f62907c..6f1e2b1 100644 --- a/docs/source/doc/llvm.core.IntegerType.rst +++ b/docs/source/doc/llvm.core.IntegerType.rst @@ -21,3 +21,10 @@ Properties [read-only] The width of the integer type, in number of bits. + + +Automatically Generated Documentation +------------------------------------- +.. autoclass:: llvm.core.IntegerType + :members: + :undoc-members: diff --git a/docs/source/doc/llvm.core.Module.rst b/docs/source/doc/llvm.core.Module.rst index 4052a4f..75cc174 100644 --- a/docs/source/doc/llvm.core.Module.rst +++ b/docs/source/doc/llvm.core.Module.rst @@ -20,3 +20,10 @@ Modules are created using the static method ``Module.new``: # create a module my_module = Module.new('my_module') + + +Automatically Generated Documentation +------------------------------------- +.. autoclass:: llvm.core.Module + :members: + :undoc-members: diff --git a/docs/source/doc/llvm.core.PointerType.rst b/docs/source/doc/llvm.core.PointerType.rst index a869fba..cc65139 100644 --- a/docs/source/doc/llvm.core.PointerType.rst +++ b/docs/source/doc/llvm.core.PointerType.rst @@ -29,3 +29,10 @@ The address space of the pointer. A `Type `_ object representing the type of the value pointed to. + + +Automatically Generated Documentation +------------------------------------- +.. autoclass:: llvm.core.PointerType + :members: + :undoc-members: diff --git a/docs/source/doc/llvm.core.StructType.rst b/docs/source/doc/llvm.core.StructType.rst index 0ac3ce6..f3b0786 100644 --- a/docs/source/doc/llvm.core.StructType.rst +++ b/docs/source/doc/llvm.core.StructType.rst @@ -1,3 +1,8 @@ llvm.core.StructType ==================== +Automatically Generated Documentation +------------------------------------- +.. autoclass:: llvm.core.StructType + :members: + :undoc-members: diff --git a/docs/source/doc/llvm.core.Type.rst b/docs/source/doc/llvm.core.Type.rst index 58883d7..b1eb354 100644 --- a/docs/source/doc/llvm.core.Type.rst +++ b/docs/source/doc/llvm.core.Type.rst @@ -126,3 +126,10 @@ Example: assert Type.int().kind == TYPE_INTEGER assert Type.void().kind == TYPE_VOID + + +Automatically Generated Documentation +------------------------------------- +.. autoclass:: llvm.core.Type + :members: + :undoc-members: diff --git a/docs/source/doc/llvm.core.User.rst b/docs/source/doc/llvm.core.User.rst index 0762729..12d40c5 100644 --- a/docs/source/doc/llvm.core.User.rst +++ b/docs/source/doc/llvm.core.User.rst @@ -37,3 +37,10 @@ The list of operands (values, of type The number of operands that this value referes to. Same as ``len(uses.operands)`` but faster if you just want the count. + + +Automatically Generated Documentation +------------------------------------- +.. autoclass:: llvm.core.User + :members: + :undoc-members: diff --git a/docs/source/doc/llvm.core.Value.rst b/docs/source/doc/llvm.core.Value.rst index fdff4cc..081d328 100644 --- a/docs/source/doc/llvm.core.Value.rst +++ b/docs/source/doc/llvm.core.Value.rst @@ -63,3 +63,10 @@ representation. ``Value`` objects can be compared for equality. Internally, this converts both arguments into their LLVM assembly representations and compares the resultant strings. + + +Automatically Generated Documentation +------------------------------------- +.. autoclass:: llvm.core.Value + :members: + :undoc-members: diff --git a/docs/source/doc/llvm.core.VectorType.rst b/docs/source/doc/llvm.core.VectorType.rst index 19b98e6..a18f6ea 100644 --- a/docs/source/doc/llvm.core.VectorType.rst +++ b/docs/source/doc/llvm.core.VectorType.rst @@ -29,3 +29,10 @@ element of the vector. [read-only] The number of elements in the vector. + + +Automatically Generated Documentation +------------------------------------- +.. autoclass:: llvm.core.VectorType + :members: + :undoc-members: From 4e87b5170aa027f71301556d5b60b3b12a7d40ed Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 24 Feb 2013 00:43:43 +0200 Subject: [PATCH 7/7] Allow Sphinx build docs with docstrings without installing module. --- docs/source/conf.py | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 5c5c38d..830f1ad 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -11,12 +11,22 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys, os +import sys, os, glob # 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. -#sys.path.insert(0, os.path.abspath('.')) +#sys.path.insert(0, os.path.abspath('../..')) + +# Support sphinx.ext.autodoc to extract docstrings from modules without installing +# complete package. +# The python modules depend on _core, so we must build entire package first though. +built_lib = glob.glob('../../build/lib.*/') +if not built_lib: + print "WARNING: To build complete documentation you must build package first" +else: + # lib dir has platform suffix + sys.path.insert(0, os.path.abspath(built_lib[0])) # -- General configuration -----------------------------------------------------