Update docs

.gitignore

@@ -1,8 +1,10 @@
 # Development
+docs
 *.session
 config.ini
 main.py
 unknown_errors.txt
+.DS_Store
 
 # Pyrogram generated code
 pyrogram/errors/exceptions/

Makefile

@@ -1,53 +1,33 @@
 VENV := venv
 PYTHON := $(VENV)/bin/python
+HOST = $(shell ifconfig | grep "inet " | tail -1 | cut -d\  -f2)
 
 RM := rm -rf
 
-.PHONY: venv build docs
+.PHONY: venv clean-build clean-api clean api build
 
 venv:
 	$(RM) $(VENV)
 	python3 -m venv $(VENV)
 	$(PYTHON) -m pip install -U pip wheel setuptools
-	$(PYTHON) -m pip install -U -r requirements.txt -r dev-requirements.txt -r docs/requirements.txt
+	$(PYTHON) -m pip install -U -r requirements.txt -r dev-requirements.txt
 	@echo "Created venv with $$($(PYTHON) --version)"
 
 clean-build:
 	$(RM) *.egg-info build dist
 
-clean-docs:
-	$(RM) docs/build
-	$(RM) docs/source/api/bound-methods docs/source/api/methods docs/source/api/types docs/source/telegram
-
 clean-api:
 	$(RM) pyrogram/errors/exceptions pyrogram/raw/all.py pyrogram/raw/base pyrogram/raw/functions pyrogram/raw/types
 
 clean:
 	make clean-build
-	make clean-docs
 	make clean-api
 
 api:
 	cd compiler/api && ../../$(PYTHON) compiler.py
 	cd compiler/errors && ../../$(PYTHON) compiler.py
 
-docs-live:
-	make clean-docs
-	cd compiler/docs && ../../$(PYTHON) compiler.py
-	$(RM) docs/source/telegram
-	$(VENV)/bin/sphinx-autobuild \
-		--host $(shell ifconfig | grep "inet " | grep -v 127.0.0.1 | cut -d\  -f2) \
-		--watch pyrogram --watch docs/resources \
-		-b html "docs/source" "docs/build/html" -j auto
-
-docs:
-	make clean-docs
-	cd compiler/docs && ../../$(PYTHON) compiler.py
-	$(VENV)/bin/sphinx-build \
-		-b html "docs/source" "docs/build/html" -j auto
-
 build:
-	make clean-build
-	make clean-api
+	make clean
 	$(PYTHON) setup.py sdist
 	$(PYTHON) setup.py bdist_wheel

compiler/api/compiler.py

@@ -16,6 +16,7 @@
 #  You should have received a copy of the GNU Lesser General Public License
 #  along with Pyrogram.  If not, see <http://www.gnu.org/licenses/>.
 
+import json
 import os
 import re
 import shutil
@@ -59,6 +60,16 @@
 namespaces_to_constructors = {}
 namespaces_to_functions = {}
 
+try:
+    with open("docs.json") as f:
+        docs = json.load(f)
+except FileNotFoundError:
+    docs = {
+        "type": {},
+        "constructor": {},
+        "method": {}
+    }
+
 
 class Combinator(NamedTuple):
     section: str
@@ -149,7 +160,7 @@ def remove_whitespaces(source: str) -> str:
     return "\n".join(lines)
 
 
-def get_docstring_arg_type(t: str, is_list: bool = False, is_pyrogram_type: bool = False):
+def get_docstring_arg_type(t: str):
     if t in CORE_TYPES:
         if t == "long":
             return "``int`` ``64-bit``"
@@ -167,9 +178,9 @@ def get_docstring_arg_type(t: str, is_list: bool = False, is_pyrogram_type: bool
     elif t == "TLObject" or t == "X":
         return "Any object from :obj:`~pyrogram.raw.types`"
     elif t == "!X":
-        return "Any method from :obj:`~pyrogram.raw.functions`"
+        return "Any function from :obj:`~pyrogram.raw.functions`"
     elif t.lower().startswith("vector"):
-        return "List of " + get_docstring_arg_type(t.split("<", 1)[1][:-1], True)
+        return "List of " + get_docstring_arg_type(t.split("<", 1)[1][:-1])
     else:
         return f":obj:`{t} <pyrogram.raw.base.{t}>`"
 
@@ -183,10 +194,7 @@ def get_references(t: str, kind: str):
         raise ValueError("Invalid kind")
 
     if t:
-        return "\n            ".join(
-            f"- :obj:`{i} <pyrogram.raw.functions.{i}>`"
-            for i in t
-        ), len(t)
+        return "\n            ".join(t), len(t)
 
     return None, 0
 
@@ -315,17 +323,33 @@ def start(format: bool = False):
 
         constructors = sorted(types_to_constructors[qualtype])
         constr_count = len(constructors)
-        items = "\n            ".join([f"- :obj:`{c} <pyrogram.raw.types.{c}>`" for c in constructors])
+        items = "\n            ".join([f"{c}" for c in constructors])
+
+        type_docs = docs["type"].get(qualtype, None)
+
+        if type_docs:
+            type_docs = type_docs["desc"]
+        else:
+            type_docs = "Telegram API base type."
 
-        docstring = f"This base type has {constr_count} constructor{'s' if constr_count > 1 else ''} available.\n\n"
-        docstring += f"    Constructors:\n        .. hlist::\n            :columns: 2\n\n            {items}"
+        docstring = type_docs
+
+        docstring += f"\n\n    Constructors:\n" \
+                     f"        This base type has {constr_count} constructor{'s' if constr_count > 1 else ''} available.\n\n" \
+                     f"        .. currentmodule:: pyrogram.raw.types\n\n" \
+                     f"        .. autosummary::\n" \
+                     f"            :nosignatures:\n\n" \
+                     f"            {items}"
 
         references, ref_count = get_references(qualtype, "types")
 
         if references:
-            docstring += f"\n\n    See Also:\n        This object can be returned by " \
-                         f"{ref_count} method{'s' if ref_count > 1 else ''}:" \
-                         f"\n\n        .. hlist::\n            :columns: 2\n\n            " + references
+            docstring += f"\n\n    Functions:\n        This object can be returned by " \
+                         f"{ref_count} function{'s' if ref_count > 1 else ''}.\n\n" \
+                         f"        .. currentmodule:: pyrogram.raw.functions\n\n" \
+                         f"        .. autosummary::\n" \
+                         f"            :nosignatures:\n\n" \
+                         f"            " + references
 
         with open(dir_path / f"{snake(module)}.py", "w") as f:
             f.write(
@@ -359,41 +383,67 @@ def start(format: bool = False):
         docstring = ""
         docstring_args = []
 
+        if c.section == "functions":
+            combinator_docs = docs["method"]
+        else:
+            combinator_docs = docs["constructor"]
+
         for i, arg in enumerate(sorted_args):
             arg_name, arg_type = arg
             is_optional = FLAGS_RE.match(arg_type)
             flag_number = is_optional.group(1) if is_optional else -1
             arg_type = arg_type.split("?")[-1]
 
+            arg_docs = combinator_docs.get(c.qualname, None)
+
+            if arg_docs:
+                arg_docs = arg_docs["params"].get(arg_name, "N/A")
+            else:
+                arg_docs = "N/A"
+
             docstring_args.append(
-                "{}{}: {}".format(
+                "{} ({}{}):\n            {}\n".format(
                     arg_name,
-                    " (optional)".format(flag_number) if is_optional else "",
-                    get_docstring_arg_type(arg_type, is_pyrogram_type=c.namespace == "pyrogram")
+                    get_docstring_arg_type(arg_type),
+                    ", *optional*".format(flag_number) if is_optional else "",
+                    arg_docs
                 )
             )
 
         if c.section == "types":
-            docstring += f"This object is a constructor of the base type :obj:`~pyrogram.raw.base.{c.qualtype}`.\n\n"
-        else:
-            docstring += f"Telegram API method.\n\n"
+            constructor_docs = docs["constructor"].get(c.qualname, None)
 
-        docstring += f"    Details:\n        - Layer: ``{layer}``\n        - ID: ``{c.id[2:].upper()}``\n\n"
+            if constructor_docs:
+                constructor_docs = constructor_docs["desc"]
+            else:
+                constructor_docs = "Telegram API type."
 
-        if docstring_args:
-            docstring += "    Parameters:\n        " + "\n        ".join(docstring_args)
+            docstring += constructor_docs + "\n"
+            docstring += f"\n    Constructor of :obj:`~pyrogram.raw.base.{c.qualtype}`."
         else:
-            docstring += "    **No parameters required.**"
+            function_docs = docs["method"].get(c.qualname, None)
+
+            if function_docs:
+                docstring += function_docs["desc"] + "\n"
+            else:
+                docstring += f"Telegram API function."
+
+        docstring += f"\n\n    Details:\n        - Layer: ``{layer}``\n        - ID: ``{c.id[2:].upper()}``\n\n"
+        docstring += f"    Parameters:\n        " + \
+                     (f"\n        ".join(docstring_args) if docstring_args else "No parameters required.\n")
 
         if c.section == "functions":
-            docstring += "\n\n    Returns:\n        " + get_docstring_arg_type(c.qualtype)
+            docstring += "\n    Returns:\n        " + get_docstring_arg_type(c.qualtype)
         else:
             references, count = get_references(c.qualname, "constructors")
 
             if references:
-                docstring += f"\n\n    See Also:\n        This object can be returned by " \
-                             f"{count} method{'s' if count > 1 else ''}:" \
-                             f"\n\n        .. hlist::\n            :columns: 2\n\n            " + references
+                docstring += f"\n    Functions:\n        This object can be returned by " \
+                             f"{count} function{'s' if count > 1 else ''}.\n\n" \
+                             f"        .. currentmodule:: pyrogram.raw.functions\n\n" \
+                             f"        .. autosummary::\n" \
+                             f"            :nosignatures:\n\n" \
+                             f"            " + references
 
         write_types = read_types = "" if c.has_flags else "# No flags\n        "
 

compiler/docs/template/bound-methods.rst

@@ -19,10 +19,6 @@ some of the required arguments.
 
     app.run()
 
-.. contents:: Contents
-    :backlinks: none
-    :local:
-
 -----
 
 .. currentmodule:: pyrogram.types

compiler/docs/template/methods.rst

@@ -14,10 +14,6 @@ the main package directly.
     with app:
         app.send_message("me", "hi")
 
-.. contents:: Contents
-    :backlinks: none
-    :local:
-
 -----
 
 .. currentmodule:: pyrogram.Client

compiler/docs/template/toctree.txt

@@ -4,4 +4,6 @@
 .. module:: {module}
 
 .. toctree::
+    :titlesonly:
+
     {entities}

compiler/docs/template/types.rst

@@ -17,10 +17,6 @@ are only returned by other methods. You also don't need to import them, unless y
 
     To tell whether a field is set or not, do a simple boolean check: ``if message.photo: ...``.
 
-.. contents:: Contents
-    :backlinks: none
-    :local:
-
 -----
 
 .. currentmodule:: pyrogram.types