From 56a959a07da5a9350632dcf860ab4e47616be04b Mon Sep 17 00:00:00 2001 From: Lonami Exo Date: Sat, 8 Apr 2017 13:58:42 +0200 Subject: [PATCH] Generate core documentation --- docs/css/docs.css | 28 ++++++- docs/generate.py | 7 ++ docs/generate_core.py | 172 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 205 insertions(+), 2 deletions(-) create mode 100644 docs/generate_core.py diff --git a/docs/css/docs.css b/docs/css/docs.css index 09745ad5..d8e9feb1 100644 --- a/docs/css/docs.css +++ b/docs/css/docs.css @@ -80,8 +80,32 @@ pre::-webkit-scrollbar-track:horizontal { pre::-webkit-scrollbar-thumb:horizontal { background: #bdd; - border-radius: 0; - height: 12px; + border-radius: 0; + height: 12px; +} + +:target { + border: 2px solid #f8f800; + background: #f8f8f8; + padding: 4px; +} + +/* 'sh' stands for Syntax Highlight */ +span.sh1 { + color: #f70; +} + +span.sh2 { + color: #0c7; +} + +span.sh3 { + color: #aaa; + font-style: italic; +} + +span.sh4 { + color: #06c; } @media (max-width: 640px) { diff --git a/docs/generate.py b/docs/generate.py index 4c7cf9ad..8293cdf6 100644 --- a/docs/generate.py +++ b/docs/generate.py @@ -4,6 +4,8 @@ import sys from docs.docs_writer import DocsWriter # Small trick so importing telethon_generator works +from docs.generate_core import write_core_index + sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..')) from telethon_generator.parser import TLParser, TLObject @@ -331,6 +333,11 @@ def generate_documentation(scheme_file): for folder in ['types', 'methods', 'constructors']: generate_index(folder, original_paths) + # Write the final core index, the main index for the rest of files + layer = TLParser.find_layer(scheme_file) + with DocsWriter(original_paths['index_all'], type_to_path_function=get_path_for_type) as docs: + write_core_index(docs, tlobjects, layer) + # Everything done print('Documentation generated.') diff --git a/docs/generate_core.py b/docs/generate_core.py new file mode 100644 index 00000000..99a0b254 --- /dev/null +++ b/docs/generate_core.py @@ -0,0 +1,172 @@ +def write_core_index(docs, tlobjects, layer): + # Determine method, types and constructors count + types = set() + method_count = 0 + constructor_count = 0 + for tlobject in tlobjects: + if tlobject.is_function: + method_count += 1 + else: + constructor_count += 1 + + types.add(tlobject.result) + + type_count = len(types) + types.clear() + + # Write the head and the full HTML + docs.write_head('Telethon API', relative_css_path='../css/docs.css') + + # Welcome text, small explanation about this page + docs.write('''

Telethon API

+

This documentation was generated straight from the scheme.tl +provided by Telegram. However, there is no official documentation per se +on what the methods, constructors and types mean. Nevertheless, this +page aims to provide easy access to all the available methods, their +definition and parameters.

+ +

Although this documentation was generated for Telethon, it may +be useful for any other Telegram library out there.

''' + + # Methods section + '''

Methods

+

Currently there are {methodcount} methods available for the layer +{layer}. The complete list can be seen here. +
+To invoke any of these methods (also called requests), you can do +as shown on the following example:

''' + + # Example usage for the methods + '''
#!/usr/bin/python3
+from telethon import TelegramClient
+from telethon.tl.functions.messages import GetHistoryRequest
+from telethon.utils import get_input_peer
+
+# Use your own values here
+api_id = 12345
+api_hash = '0123456789abcdef0123456789abcdef'
+phone_number = '+34600000000'
+
+# Create the client and connect
+client = TelegramClient('username', api_id, api_hash)
+client.connect()
+
+# Ensure you're authorized
+if not client.is_user_authorized():
+    client.send_code_request(phone)
+    client.sign_in(phone, input('Enter the code: '))
+
+# Using built-in methods
+dialogs, entities = client.get_dialogs(10)
+entity = entities[0]
+
+# !! Invoking a request manually !!
+result = client.invoke(
+    GetHistoryRequest(
+        get_input_peer(entity),
+        limit=20,
+        offset_date=None,
+        offset_id=0,
+        max_id=0,
+        min_id=0,
+        add_offset=0))
+
+# Now you have access to the first 20 messages
+messages = result.messages
''' + + # Example end + '''

As you can see, manually invoking requests with client.invoke() +is way more verbose than using the built-in methods. However, and given +that there are so many methods available, it's impossible to provide a nice +interface to things that may change over time. To get full access, however, +you're still able to invoke these methods manually.

''' + + # Types section + '''

Types

+

Currently there are {typecount} types. You can see the full +list here.

+ +

The Telegram types are the abstract results that you receive +after invoking a request. They are "abstract" because they can have +multiple constructors. For instance, the abstract type User +can be either UserEmpty or User. You should, +most of the time, make sure you received the desired type by using +the isinstance(result, Constructor) Python function. + +When a request needs a Telegram type as argument, you should create +an instance of it by using one of its, possibly multiple, constructors.

''' + + # Constructors section + '''

Constructors

+

Currently there are {constructorcount} constructors. You can see +the full list here.

+ +

Constructors are the way you can create instances of the abstract types +described above, and also the instances which are actually returned from +the functions although they all share a common abstract type.

''' + + # Core types section + '''

Core types

+

Core types are types from which the rest of Telegram types build upon:

+'''.format( + layer=layer, + typecount=type_count, + methodcount=method_count, + constructorcount=constructor_count + )) + docs.end_body()