Skript generate_module_docs

Dokumentace skriptu docs/generate_module_docs.py.

Funkce

check_content_changed(content, output_file)

Zkontroluje, zda se obsah liší od existujícího souboru.

Parametry:

  • content – Nový obsah k porovnání.

  • output_file – Cesta k existujícímu souboru.

Vrací:

True, pokud se obsah změnil nebo soubor neexistuje

extract_url_patterns(urls_file)

Extrahujte vzory URL ze souboru urls.py.

Parametry:

urls_file – Cesta k souboru urls.py.

Vrací:

Každý url_pattern je slovník s klíči: pattern, view, `name`

parse_path_call(node)

Analyzuje volání path() nebo re_path() a extrahuje informace o vzoru URL.

Parametry:

node – uzel AST představující volání path().

Vrací:

`dict: {'pattern': str, 'view': str, 'name': str} or None`

generate_url_routing_rst()

Vygeneruje dokumentaci k směrování URL pro všechny moduly.

Vytvoří docs/source/04_django_aplikace/04_01_core/url_routing.rst s tabulkami všech vzorů URL z urls.py každého modulu.

Vrací:

True, pokud úspěšné, jinak false

extract_signals(signals_file)

Extrahuje přijímače signálu ze souboru signals.py.

Parametry:

signals_file – Cesta k souboru signals.py.

Vrací:

Seznam slovníků informací o signálech s klíči: function, signal_type, sender, `weak`

parse_receiver_decorator(decorator, function_name)

Analyzujte dekorátor @receiver(), abyste extrahovali informace o signálu.

Parametry:

  • decorator – AST Volací uzel představující @receiver()

  • function_name – Název dekorované funkce

Vrací:

`dict: {'function': str, 'signal_type': str, 'sender': str, 'weak': str} or None`

generate_signals_rst()

Vygeneruje dokumentaci signálů pro všechny moduly.

Vytvoří docs/source/04_django_aplikace/04_01_core/signals.rst s tabulkami všech přijímačů signálů z každého modulu signals.py

Vrací:

True v případě úspěchu, False v opačném případě.

extract_permissions(models_file)

Extrahuje možnosti akcí z třídy Permissions v models.py.

Parametry:

models_file – Cesta k souboru models.py.

Vrací:

Seznam názvů akcí (např. adb_smazat, `vb_smazat`)

generate_permissions_rst()

Vygeneruje dokumentaci oprávnění.

Aktualizuje docs/source/04_django_aplikace/04_01_core/permissions.rst připojením seznamu všech definovaných akcí z Permissions.actionChoices za nadpis „Uživatelské akce řízené pomocí oprávnění”.

Vrací:

True, pokud úspěšné, jinak False.

clean_comment_value(value)

Odstraní obalové uvozovky/závorky z hodnoty komentáře.

Parametry:

value – Parametr value pracuje se s atributy strip.

Vrací:

Hodnota vrácená funkcí podle aktuální logiky implementace.

parse_comment_values(comment_text)

Vrátí mapované hodnoty získané z inline komentáře XSD.

Parametry:

comment_text – Číselná hodnota comment_text použitá při výpočtu nebo transformaci.

Vrací:

Hodnota vrácená funkcí podle aktuální logiky implementace.

get_following_comment(parent, element)

Najde první uzel komentáře bezprostředně za daným elementem.

Parametry:

  • parent – Parametr parent se předává do volání list().

  • element – Parametr element ovlivňuje větvení podmínek.

Vrací:

Hodnota vrácená funkcí podle aktuální logiky implementace.

collect_choice_element_names(choice_element)

Shromáždí názvy všech uzlů xs:element uvnitř bloku choice.

Parametry:

choice_element – Parametr choice_element slouží jako vstup pro logiku funkce collect_choice_element_names.

Vrací:

Hodnota vrácená funkcí podle aktuální logiky implementace.

format_choice_note(names)

Naformátuje poznámku popisující možnosti uvnitř elementu choice.

Parametry:

names – Kolekce names zpracovávaná touto funkcí.

Vrací:

Hodnota vrácená funkcí podle aktuální logiky implementace.

extract_elements_from_parent(parent, choice_context)

Rekurzivně extrahuje definice elementů a zaznamená kontext choice, pokud existuje.

Parametry:

  • parent – Parametr parent se předává do volání get_following_comment().

  • choice_context – Kolekce choice_context zpracovávaná touto funkcí.

Vrací:

Hodnota vrácená funkcí podle aktuální logiky implementace.

extract_elements_from_complex_type(complex_type)

Extrahuje řádky elementů z definice complexType.

Parametry:

complex_type – Parametr complex_type slouží jako vstup pro logiku funkce extract_elements_from_complex_type.

Vrací:

Hodnota vrácená funkcí podle aktuální logiky implementace.

extract_model_mappings(schema_root)

Načte mapování z volby elementu amcr do řádků Model -> ComplexType.

Parametry:

schema_root – Parametr schema_root pracuje se s atributy find.

Vrací:

Hodnota vrácená funkcí podle aktuální logiky implementace.

extract_xsd_version(schema_root)

Extrahuje atribut verze z kořenového prvku schématu XSD.

Parametry:

schema_root – Kořenový prvek schématu XSD.

Vrací:

Verze (např. „2.2“) nebo „neznámá“, pokud nebyla nalezena

extract_django_command_info(command_file)

Extrahuje informace o dokumentaci ze souboru příkazů pro správu Django.

Parametry:

command_file – Cesta k příkazovému souboru.

Vrací:

`dict: {'name': str, 'help': str, 'docstring': str, 'arguments': list}`

extract_command_arguments(add_arguments_node)

Extrahuje definice argumentů z metody add_arguments.

Parametry:

add_arguments_node – AST uzel metody add_arguments.

Vrací:

Seznam slovníků s informacemi o argumentech s klíči: name, type, help, `default`

generate_management_commands_rst()

Vygeneruje dokumentaci k příkazům pro správu.

Vytvoří docs/source/04_django_aplikace/04_01_core/management_commands.rst s dokumentací ke všem příkazům pro správu Django v core/management/commands.

Vrací:

True, pokud úspěšné, jinak False.

generate_export_structure_rst()

Vygeneruje docs/source/05_integrace/export_structure.rst ze souboru amcr.xsd.

Vrací:

Hodnota vrácená funkcí podle aktuální logiky implementace.

has_meaningful_code(source_file)

Zkontroluje, zda soubor Python obsahuje smysluplný kód (nejen komentáře).

Parametry:

source_file – Cesta k souboru.

Vrací:

rue, pokud soubor obsahuje smysluplný kód, False v opačném případě.

extract_docstrings(source_file)

Extrahuje docstrings z modulu Python pomocí AST parsování.

Parametry:

source_file – Cesta ke zdrojovému souboru.

Vrací:

tuple: (třídy, funkce), kde každá je seznamem slovníků.

format_docstring_for_rst(docstring, indent)

Formátuje docstring ve stylu Google pro výstup RST.

Převádí sekce Args:, Returns: atd. do správného formátu RST s názvy argumentů uzavřenými v zpětných lomítkách. Názvy sekcí jsou přeloženy do češtiny.

Parametry:

  • docstring – Docstring, který se má formátovat

  • indent – Prefix odsazení pro každý řádek.

Vrací:

Seznam formátovaných řádků RST.

generate_rst_explicit(source_file, module_name, module_title, module_description)

Vygeneruje soubor RST s explicitním obsahem docstringu.

Parametry:

  • source_file – Cesta k zdrojovému souboru.

  • module_name – Plně kvalifikovaný název modulu.

  • module_title – Název souboru RST.

  • module_description – Popis modulu.

Vrací:

Vygenerovaný obsah RST.

generate_rst_autodoc(module_name, module_title, module_description)

Vygeneruje soubor RST pomocí direktiv Sphinx autodoc.

Parametry:

  • module_name – Plně kvalifikovaný název modulu.

  • module_title – Název souboru RST`.

  • module_description – HPopis modulu.

Vrací:

Vygenerovaný obsah RST.

get_module_title_and_description(module_dir_name, filename)

Předá příslušný název a popis souboru modulu.

Parametry:

  • module_dir_name – Název adresáře modulu (např. adb, core).

  • filename – Název souboru Python (např. models.py).

Vrací:

tuple: (title, description)

generate_rst_for_file(source_file, module_dir_name, output_dir, mode)

Vygeneruje dokumentaci RST pro jeden soubor Python.

Parametry:

  • source_file – Cesta ke zdrojovému souboru Python.

  • module_dir_name – Název adresáře modulu.

  • output_dir – Výstupní adresář pro soubory RST.

  • mode – Režim generování (autodoc nebo explicit).

Vrací:

True v případě úspěchu, False v opačném případě.

generate_index_rst(module_dir_name, generated_files, output_dir)

Vygeneruje soubor index.rst s toctree všech vygenerovaných modulů.

Parametry:

  • module_dir_name – Název adresáře modulu.

  • generated_files – Seznam vygenerovaných názvů souborů Python.

  • output_dir – Výstupní adresář.

Vrací:

True v případě úspěchu, False v opačném případě

process_module(module_dir_name, mode)

Zpracuje jeden adresář modulu.

Parametry:

  • module_dir_name – Název adresáře modulu.

  • mode – Režim generování (autodoc nebo explicit).

Vrací:

True, pokud byly vygenerovány nějaké soubory.

get_all_modules()

Získá všechny adresáře modulů Django z webového klienta.

Vrací:

Seznam názvů adresářů modulů.

generate_all_modules(mode, specific_module)

Vygeneruje soubory RST pro všechny moduly nebo konkrétní modul.

Parametry:

  • mode – Režim generování (autodoc nebo explicit).

  • specific_module – Konkrétní modul, který se má zpracovat, nebo None pro všechny.

Vrací:

True, pokud byla vygenerována nějaká dokumentace.

generate_rst_for_docs_script(source_file, output_dir, mode)

Vygeneruje dokumentaci RST pro jeden Python skript v adresáři docs/.

Parametry:

  • source_file – Cesta ke zdrojovému souboru Python v docs/.

  • output_dir – Výstupní adresář pro soubory RST.

  • mode – Režim generování (autodoc nebo explicit).

Vrací:

True v případě úspěchu, False v opačném případě.

generate_docs_scripts_index_rst(generated_files, output_dir)

Vygeneruje index.rst pro dokumentační skripty v docs/.

Parametry:

  • generated_files – Seznam vygenerovaných názvů souborů Python.

  • output_dir – Výstupní adresář.

Vrací:

True v případě úspěchu, False v opačném případě.

generate_docs_scripts_docs(mode)

Vygeneruje RST dokumentaci pro všechny *.py skripty v docs/.

Parametry:

mode – Režim generování (autodoc nebo explicit).

Vrací:

True, pokud byl vygenerován alespoň jeden soubor.

get_script_language(script_name)

Vrátí jazyk pro zvýraznění syntaxe podle přípony souboru.

Parametry:

script_name – Parametr script_name předává se do volání Path().

Vrací:

Vrací hodnotu typu str (str).

get_script_doc_name(script_name)

Vrátí bezpečný název RST souboru pro skript.

Parametry:

script_name – Parametr script_name předává se do volání sub(), vstupuje do návratové hodnoty.

Vrací:

Vrací hodnotu typu str (výsledek volání lower()).

generate_rst_for_project_script(source_file, output_dir)

Vygeneruje RST dokumentaci pro jeden soubor v adresáři scripts/.

Parametry:

  • source_file – Parametr source_file předává se do volání get_script_doc_name(), get_script_language(), pracuje se s atributy name.

  • output_dir – Parametr output_dir slouží jako vstup pro logiku funkce generate_rst_for_project_script.

Vrací:

Vrací hodnotu typu bool podle vyhodnocení podmínek.

generate_project_scripts_index_rst(toctree_entries, output_dir)

Vygeneruje index.rst pro skripty v adresáři scripts/.

Parametry:

  • toctree_entries – Parametr toctree_entries předává se do volání sorted().

  • output_dir – Parametr output_dir slouží jako vstup pro logiku funkce generate_project_scripts_index_rst.

Vrací:

Vrací hodnotu typu bool podle vyhodnocení podmínek.

generate_project_scripts_docs()

Vygeneruje RST dokumentaci pro soubory v scripts/.

Vrací:

Vrací hodnotu typu bool podle vyhodnocení podmínek.

build_docs()

Vytvoří HTML dokumentaci pomocí Sphinx.

Vrací:

True, pokud se sestavení podařilo, False v opačném případě.

main()

Hlavní funkce pro spuštění generátoru dokumentace.