Update docs to support Sphinx v3

README.md

@@ -67,7 +67,7 @@ python3.8 -m pip install .
 
 ## License
 
-The mcdecoder uses MIT License. See [LICENSE](https://github.com/wildlarva/mcdecoder/blob/master/LICENSE) for more details.
+The mcdecoder uses MIT License. See [LICENSE](LICENSE) for more details.
 
 ## More details about usage
 

requirements.txt

@@ -3,11 +3,10 @@ deprecation<2.1
 Jinja2
 jsonschema
 lark-parser
-m2r
 numpy
 pytest
 PyYAML
-Sphinx
+Sphinx>=3
 sphinx-argparse
 sphinx-jsonschema
 sphinx_rtd_theme

src_docs/README.rst

@@ -1 +1,90 @@
-.. mdinclude:: ../README.md
+README: mcdecoder
+=================
+
+The mcdecoder (Machine Code Decoder) is a set of tools to implement a machine code decoder. It includes tools to:
+
+* Generate a decoder for a user-defined machine code specification
+* Emulate a decoder for a binary data and show decoded result
+* Check the integrity of a machine code specification
+* etc.
+
+Quickstart
+----------
+
+#. Define your machine code specification
+
+   .. code-block:: yaml
+      :caption: arm.yaml
+
+       machine:
+         byteorder: little
+       instructions:
+         - name: add_immediate_a1
+           format: xxxx:cond|00|1|0100|x:S|xxxx:Rn|xxxx:Rd|xxxx xxxx xxxx:imm12
+
+#. Generate a decoder
+
+   .. code-block:: bash
+
+       mcdecoder generate arm.yaml
+
+#. Use the decoder from a client
+
+   .. code-block:: c
+
+       const uint8_t kMachineCodes[] = { 0x04, 0xB0, 0x8D, 0xE2, };
+       DecodeRequest request;
+       DecodeResult result;
+       bool succeeded;
+
+       request.codes = &kMachineCodes[0];
+       succeeded = DecodeInstruction(&request, &result);
+
+For more details, follow Installation steps below and go on to :doc:`quickstart`.
+
+Who is mcdecoder for
+--------------------
+
+* Developers of a CPU emulator
+
+  * To implement the decoder part of an emulator
+
+* Developers of a static analyzer for machine codes
+
+  * To implement the decoder part of an analyzer
+
+* Learners of the basics about machine codes
+
+  * Hands-on approach to learn: write and test actual machine codes
+
+Implementing and maintaining a decoder are tough and cumbersome. The mcdecoder soothes these pains by generating a decoder.
+The mcdecoder was originally developed for `athrill <https://github.com/tmori/athrill/>`__, a CPU emulator. It will be independent from athrill and be a more general tool in the near future.
+
+Requirements
+------------
+
+* Python 3.8 (with pip)
+
+Installation
+------------
+
+.. code-block:: bash
+
+    git clone https://github.com/wildlarva/mcdecoder.git
+    cd mcdecoder
+    python3.8 -m pip install .
+
+License
+-------
+
+The mcdecoder uses MIT License. See `LICENSE <https://github.com/wildlarva/mcdecoder/blob/master/LICENSE>`__ for more details.
+
+More details about usage
+------------------------
+
+See :doc:`documents for mcdecoder users <guides>`.
+
+For developers of mcdecoder
+---------------------------
+
+See :doc:`documents for mcdecoder developers <dev_docs>`.

src_docs/conf.py

@@ -31,7 +31,6 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    # 'm2r',
     'sphinx.ext.autodoc',
     'sphinx.ext.graphviz',
     'sphinx-jsonschema',

src_docs/guides.rst

@@ -6,6 +6,6 @@ User guides
     :maxdepth: 2
     :caption: Contents:
 
-    README <README>
+    README
     quickstart
     user_templates

src_docs/spec_mc_desc.rst

@@ -377,9 +377,16 @@ decoder.process_instruction_hook
 
 .. warning::
 
-    This is an experimental feature. The name and forms of this attribute might be changed in the future release.
+    This is an experimental feature. The name and form of this attribute might be changed in the future release.
 
-:code:`process_instruction_hook` defines the name of the hook function to to process user-specific information into a different form.
+:code:`process_instruction_hook` defines the name of the hook function to process user-specific information for an instruction into a different form.
+The hook function must be defined in the python config file named :code:`config.py`. Yoo must put the config file in the same directory as the MC description file.
+
+The signature of the hook function is
+
+.. code-block:: python
+
+    def <name_of_hook_function>(instruction: InstructionDecoder) -> None:
 
 Here's an example of defining a hook function to process user-specific information.
 

src_docs/spec_mcdecoder_api.rst

@@ -42,23 +42,23 @@ Here's an example of using :code:`DecodeInstruction` (without namespace).
 Types
 *********************************
 
-.. c:type:: struct DecodeRequest
+.. c:struct:: DecodeRequest
 
     Decoding request
 
     .. c:member:: const uint8_t *codes
 
         Codes to be input
 
-.. c:type:: struct DecodeResult
+.. c:struct:: DecodeResult
 
     Decoding result
 
     .. c:member:: InstructionId instruction_id
 
         Decoded instruction id
 
-    .. c:member:: unnamed union instruction
+    .. c:union:: instruction
 
         Decoding result for an instruction
 
@@ -70,23 +70,23 @@ Types
 
             * <instruction>: Instruction name
 
-.. c:type:: enum InstructionId
+.. c:enum:: InstructionId
 
     Instruction id to identify a decoded instruction
 
-    .. c:member:: InstructionId_k_<instruction>
+    .. c:enumerator:: InstructionId_k_<instruction>
 
         Id for <instruction>
 
         where
 
         * <instruction>: Instruction name
 
-    .. c:member:: InstructionId_kUnknown
+    .. c:enumerator:: InstructionId_kUnknown
 
         Id for an unknown instruction
 
-.. c:type:: struct InstructionDecodeResult_<instruction>
+.. c:struct:: InstructionDecodeResult_<instruction>
 
     Decoding result for <instruction>
 
@@ -107,7 +107,7 @@ Types
 Macros
 *********************************
 
-.. c:macro:: InstructionId INSTRUCTION_ID_MAX
+.. c:var:: InstructionId INSTRUCTION_ID_MAX
 
     Number of instruction ids