misc, fix source link in docs

.gitignore

@@ -1,9 +1,11 @@
 # Common directories
-build/
-target/
+local/
+var/
 run/
 tmp/
 dist/
+build/
+target/
 
 # Native objects
 *.o

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 {}

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("/")

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 <https://bitbucket.org/Cosmius/gugugu/src/master/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 <https://bitbucket.org/Cosmius/gugugu/src/master/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 <https://bitbucket.org/Cosmius/gugugu/src/master/examples/lang/haskell/app/jsonhttp-client.hs>`_
+:gugugu-source:`examples/lang/haskell/app/jsonhttp-client.hs`
 for how to write a ``ClientTransport``.
 
 

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 <https://bitbucket.org/Cosmius/gugugu/src/master/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 <https://bitbucket.org/Cosmius/gugugu/src/master/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 <https://bitbucket.org/Cosmius/gugugu/src/master/examples/lang/python/src/guguguexamples/jsonhttp/client.py>`_
+:gugugu-source:`examples/lang/python/src/guguguexamples/jsonhttp/client.py`
 for how to write a ``ClientTransport``.
 
 

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 <https://bitbucket.org/Cosmius/gugugu/src/master/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 <https://bitbucket.org/Cosmius/gugugu/src/master/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 <https://bitbucket.org/Cosmius/gugugu/src/master/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``.
 
 

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 <https://bitbucket.org/Cosmius/gugugu/src/master/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/ <https://bitbucket.org/Cosmius/gugugu/src/master/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/ <https://bitbucket.org/Cosmius/gugugu/src/master/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

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 <https://bitbucket.org/Cosmius/gugugu/src/master/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 <https://bitbucket.org/Cosmius/gugugu/src/master/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 <https://bitbucket.org/Cosmius/gugugu/src/master/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