diff --git a/.gitignore b/.gitignore index 2869320..88c9e5c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,9 +1,11 @@ # Common directories -build/ -target/ +local/ +var/ run/ tmp/ dist/ +build/ +target/ # Native objects *.o diff --git a/docs/_ext/gugugu.py b/docs/_ext/gugugu.py new file mode 100644 index 0000000..5b8de67 --- /dev/null +++ b/docs/_ext/gugugu.py @@ -0,0 +1,25 @@ +from functools import partial +from docutils.nodes import reference, literal +from sphinx.config import Config + + +def gugugu_source_role(name, rawtext, text, lineno, inliner, options=None, + content=None, *, config): + + if options is None: + options = dict() + get_source_link = config.gugugu_get_source_link + if get_source_link is None: + node = literal(rawtext, text, **options) + else: + link = get_source_link(text) + node = reference( + rawsource=rawtext, text=text, refuri=link, **options) + return [node], [] + + +def setup(app): + app.add_config_value("gugugu_get_source_link", None, "env") + app.add_role("gugugu-source", partial(gugugu_source_role, config=app.config)) + + return {} diff --git a/docs/conf.py b/docs/conf.py index 248d7d0..5a50533 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,9 +10,9 @@ # 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. # -# import os -# import sys -# sys.path.insert(0, os.path.abspath(".")) +import os +import sys +sys.path.append(os.path.abspath("./_ext")) import yaml from pathlib import Path @@ -38,6 +38,7 @@ # extensions coming with Sphinx (named "sphinx.ext.*") or your custom # ones. extensions = [ + "gugugu", ] # Add any paths that contain templates here, relative to this directory. @@ -68,3 +69,8 @@ "Prebuilt binaries": "https://bitbucket.org/Cosmius/gugugu/downloads/", }, } + + +def gugugu_get_source_link(path: str): + rv = f"https://github.com/Cosmius/gugugu/blob/master/{path}" + return rv.rstrip("/") diff --git a/docs/lang/haskell.rst b/docs/lang/haskell.rst index 6d745db..cbcd68c 100644 --- a/docs/lang/haskell.rst +++ b/docs/lang/haskell.rst @@ -149,7 +149,7 @@ They have kind ``* -> * -> (* -> *) -> (* -> *) -> Constraint``. and usually have instances of ``MonadError`` / ``MonadState``. You might find -`examples/lang/haskell/src/GuguguExamples/Codec/Json.hs `_ +:gugugu-source:`examples/lang/haskell/src/GuguguExamples/Codec/Json.hs` useful to write ``EncoderImpl``/``DecoderImpl``. Most class members do not use ``r`` and ``g`` except the following two. @@ -371,7 +371,7 @@ and should return ``f ra -> m (g rb)``, the handler with ``ra`` and ``rb`` with decoding/encoding handled. Please consult -`examples/lang/haskell/app/jsonhttp-server.hs `_ +:gugugu-source:`examples/lang/haskell/app/jsonhttp-server.hs` for how to use the it. Client Usage @@ -410,7 +410,7 @@ The ``ClientTransport`` is called with, and should return ``m (g b)``, the response. Please consult -`examples/lang/haskell/app/jsonhttp-client.hs `_ +:gugugu-source:`examples/lang/haskell/app/jsonhttp-client.hs` for how to write a ``ClientTransport``. diff --git a/docs/lang/python.rst b/docs/lang/python.rst index 7a13f3e..48c318f 100644 --- a/docs/lang/python.rst +++ b/docs/lang/python.rst @@ -184,7 +184,7 @@ The ``S`` is the state used in encoding/decoding. The ``R`` is the serialized type encoding to or decoding from. You might find -`examples/lang/python/src/guguguexamples/codec/json.py `_ +:gugugu-source:`examples/lang/python/src/guguguexamples/codec/json.py` useful to write a ``EncoderImpl``/``DecoderImpl``. Most functions in the types works with only ``S`` except the following two. @@ -501,7 +501,7 @@ and you are responsible to handle that. The function should be polymorphic over type ``A`` and ``B``. Please consult -`examples/lang/python/src/guguguexamples/jsonhttp/server.py `_ +:gugugu-source:`examples/lang/python/src/guguguexamples/jsonhttp/server.py` for how to use the it. Client Usage @@ -542,7 +542,7 @@ and return an response about type ``RB``. Like ``ServerCodecHandler``, you are responsible to handle possible exceptions. Please consult -`examples/lang/python/src/guguguexamples/jsonhttp/client.py `_ +:gugugu-source:`examples/lang/python/src/guguguexamples/jsonhttp/client.py` for how to write a ``ClientTransport``. diff --git a/docs/lang/rust.rst b/docs/lang/rust.rst index 36a582f..fb7969c 100644 --- a/docs/lang/rust.rst +++ b/docs/lang/rust.rst @@ -165,7 +165,7 @@ They both have three associated types ``Repr``, ``Error`` and ``State``. - The ``State`` is the intermediate state used during encoding or decoding. You might find -`examples/lang/rust/src/codec/json.rs `_ +:gugugu-source:`examples/lang/rust/src/codec/json.rs` useful to write implementation for ``EncoderImpl``/``DecoderImpl``. Most trait functions do not use ``Repr`` except the following two. @@ -517,7 +517,7 @@ it should handle a request deserialized from ``RA`` with response serialized to ``RB``. Please consult -`examples/lang/rust/src/bin/gugugu-example-rust-jsonhttp-server.rs `_ +:gugugu-source:`examples/lang/rust/src/bin/gugugu-example-rust-jsonhttp-server.rs` for how to use the it. Client Usage @@ -561,7 +561,7 @@ Like ``ServerCodecHandler``, deserialized from ``RB``. Please consult -`examples/lang/rust/src/bin/gugugu-example-rust-jsonhttp-client.rs `_ +:gugugu-source:`examples/lang/rust/src/bin/gugugu-example-rust-jsonhttp-client.rs` for how to write a ``ClientTransport``. diff --git a/docs/lang/scala.rst b/docs/lang/scala.rst index e9fe619..049f7e2 100644 --- a/docs/lang/scala.rst +++ b/docs/lang/scala.rst @@ -159,7 +159,7 @@ The ``S`` is the state used in encoding/decoding. The ``R`` is the serialized type encoding to or decoding from. You might find -`examples/lang/scala/src/main/scala/guguguexamples/codec/JsonCodecImpl.scala `_ +:gugugu-source:`examples/lang/scala/src/main/scala/guguguexamples/codec/JsonCodecImpl.scala` useful to write a ``EncoderImpl``/``DecoderImpl``. Most functions in the traits works with only ``S`` except the following two. @@ -417,7 +417,7 @@ corresponding ``EncoderImpl``/``DecoderImpl``, and you are responsible to handle that. Please consult -`examples/lang/scala/src/main/scala/guguguexamples/jsonhttp/server/ `_ +:gugugu-source:`examples/lang/scala/src/main/scala/guguguexamples/jsonhttp/server/` for how to use the ``ServerTransport``. Client Usage @@ -442,7 +442,7 @@ and return an response about type ``RB``. Like ``ServerCodecHandler``, you are responsible to handle possible exceptions. Please consult -`examples/lang/scala/src/main/scala/guguguexamples/jsonhttp/client/ `_ +:gugugu-source:`examples/lang/scala/src/main/scala/guguguexamples/jsonhttp/client/` for how to write a ``ClientTransport``. Command Line Options diff --git a/docs/lang/typescript.rst b/docs/lang/typescript.rst index 22ce543..28b2121 100644 --- a/docs/lang/typescript.rst +++ b/docs/lang/typescript.rst @@ -176,7 +176,7 @@ The ``S`` is the state used in encoding/decoding. The ``R`` is the serialized type encoding to or decoding from. You might find -`examples/lang/typescript/src/codec/json-codec.ts `_ +:gugugu-source:`examples/lang/typescript/src/codec/json-codec.ts` useful to write a ``EncoderImpl``/``DecoderImpl``. Most functions in the interfaces works with only ``S`` except the following two. @@ -412,7 +412,7 @@ corresponding ``EncoderImpl``/``DecoderImpl``, and you are responsible to handle that. Please consult -`examples/lang/typescript/src/jsonhttp/server.ts `_ +:gugugu-source:`examples/lang/typescript/src/jsonhttp/server.ts` for how to use the ``ServerTransport``. Client Usage @@ -445,7 +445,7 @@ and return an response about type ``RB``. Like ``ServerCodecHandler``, you are responsible to handle possible exceptions. Please consult -`examples/lang/typescript/src/jsonhttp/client.ts `_ +:gugugu-source:`examples/lang/typescript/src/jsonhttp/client.ts` for how to write a ``ClientTransport``. Command Line Options