Próbuję udokumentować pakiet python z sphinx i udało się wygenerować pliki html. Pakiet, który dokumentuję, składa się z zestawu plików *.py, z których większość zawiera jedną klasę z kilkoma plikami będącymi oryginalnymi modułami z określonymi funkcjami. Nie muszę ujawniać faktu, że każda klasa znajduje się w module, więc dodałem odpowiednie instrukcje from w pliku __init__.py, np.Jak dokumentować klasy bez nazwy modułu?
from base import Base
, dzięki czemu użytkownik może korzystać z komendy import pkg a nie wtedy trzeba określić moduł, który zawiera klasę:
import pkg
class MyBase(pkg.Base): # instead of pkg.base.Base ...
...
Problemem jest to, że sfinks kładzie nacisk na dokumentowanie klasę jako pkg.base.Base. Próbowałem ustawić add_module_names = False w conf.py. Jednak w rezultacie sfinks pokazuje klasę jako po prostu Base zamiast pkg.Base. Dodatkowo to psuje dokumentację kilku plików *.py, które są są modułami.
Jak zrobić sphinx pokazać klasę jako pkg.Base? A jak ustawić selektywnie dyrektywę add_module_names dla każdego pliku *.py?
Nie rób tego. Sfinks ** poprawnie ** mówi użytkownikowi, gdzie klasa jest * zdefiniowana *, a nie gdzie jest importowana. Jeśli importujesz klasę 'Base' w dwóch różnych modułach, w jaki sposób Sphinx może określić nazwę, której chcesz użyć? Jeśli nie chcesz, aby użytkownik wiedział o module, w którym definiujesz klasę, powinieneś uczynić ją prywatną (co, jeśli dobrze pamiętam, nie będzie wyświetlane w wygenerowanych plikach). – Bakuriu
@Bakuriu - Nie jestem pewien, czy rozumiem Twój komentarz. Aby wyjaśnić, jedynym powodem, dla którego każda klasa znajduje się w oddzielnym pliku, jest ułatwienie zarządzania kontrolą kodu źródłowego. Używanie klas wymaga tylko nazw pakietów i klas, a nie nazwy modułu (która jest zbędna). Dokumentacja powinna opisywać użycie, a nie definicję, nie sądzisz? Jak ustawić nazwę modułu jako prywatną? –
Więc w czym problem? Po prostu użyj 'add_module_names = False' i umieść dokumentację na właściwej stronie. Użytkownicy zobaczą, że na stronie odnoszącej się do modułu 'pkg' znajduje się udokumentowana klasa' Base' i jest w porządku. Tylko 'pkg.module.Base ** ** odnosi się do modułu, w którym zdefiniowana jest klasa, a nie tam, gdzie" go używasz "(co nie jest dobrze zdefiniowane). Jeśli potrzebujesz brudnego rozwiązania, aby uzyskać pożądany wynik, to w '__init__' utwórz fałszywą podklasę:' class TheClass (pkg.module.TheClass): pass', dziedzicząc dokumentację. – Bakuriu