Source documentation/pl: Difference between revisions

From FreeCAD Documentation
(Updating to match new version of source page)
No edit summary
 
(37 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<languages/>
<languages/>

{{Docnav
{{Docnav/pl
|[[Extra python modules|Extra python modules]]
|[[Extra_python_modules/pl|Dodatkowe moduły Python]]
|[[List of Commands|List of Commands]]
|[[Contributors/pl|Współtwórcy]]
}}
}}

{{TOCright}}
{{TOCright}}
==Overview==
The FreeCAD source code is commented to allow automatic programming documentation generation using [[Doxygen|Doxygen]], a popular source code documentation system. Doxygen can document both the C++ and Python parts of FreeCAD, resulting in HTML pages with hyperlinks to each documented function and class.


==Przegląd==
The documentation is hosted online at the [http://www.freecadweb.org/api/ FreeCAD API website]. Please note that this documentation may not always be up to date; if you need more details, download FreeCAD's latest source code and compile the documentation yourself. If you have pressing questions about the code please ask in the developer section of the [https://forum.freecadweb.org/index.php FreeCAD forum].

Kod źródłowy FreeCAD jest komentowany, aby umożliwić automatyczne generowanie dokumentacji programistycznej przy użyciu narzędzia [[Doxygen/pl|Doxygen]], popularnego systemu dokumentacji kodu źródłowego. Doxygen może udokumentować zarówno C++ jak i Python będącego nieodzowną częścią FreeCAD, czego wynikiem są strony HTML z hiperłączami do każdej udokumentowanej funkcji i klasy.

Dokumentacja jest przechowywana online na stronie [https://freecad.github.io/SourceDoc/ FreeCAD API]. Proszę zauważyć, że ta dokumentacja może nie zawsze być aktualna. Jeśli potrzebujesz więcej szczegółów, pobierz najnowszy kod źródłowy FreeCAD i skompiluj dokumentację samodzielnie. Jeśli masz pilne pytania dotyczące kodu, zapytaj w sekcji dla deweloperów na [https://forum.freecadweb.org/index.php forum FreeCAD].


Compiling the API documentation follows the same general steps as compiling the FreeCAD executable, as indicated in the [[Compile_on_Linux/Unix|compile on Unix]] page.
Kompilacja dokumentacji API przebiega tak samo jak kompilacja pliku wykonywalnego programu FreeCAD, jak wskazano na stronie [[Compile_on_Linux/pl|Kompilacja w Linux OS]].


[[File:FreeCAD_documentation_compilation_workflow.svg|800px]]
[[File:FreeCAD_documentation_compilation_workflow.svg|800px]]


{{Caption|Ogólny przepływ pracy w celu skompilowania dokumentacji programistycznej programu FreeCAD. W systemie muszą znajdować się pakiety Doxygen i Graphviz, a także sam kod źródłowy FreeCAD. CMake konfiguruje system tak, aby za pomocą jednej instrukcji make dokumentacja całego projektu została skompilowana do wielu plików HTML z diagramami.}}
{{Caption|General workflow to compile FreeCAD's programming documentation. The Doxygen and Graphviz packages must be in the system, as well as the FreeCAD source code itself. CMake configures the system so that with a single make instruction the documentation for the the entire project is compiled into many HTML files with diagrams.}}


<span id="Build_source_documentation"></span>
== Build source documentation ==
==Zbuduj dokumentację źródłową==


<span id="Complete_documentation"></span>
If you have Doxygen installed, it is very easy to build the documentation. Also install [https://www.graphviz.org/ Graphviz] to be able to produce diagrams showing the relationships between different classes and libraries in the FreeCAD code. Graphviz is also used by FreeCAD's [[Std_ExportGraphviz|dependency graph]] to show the relationships between different objects.
===Pełna dokumentacja===

Jeśli masz zainstalowany Doxygen, bardzo łatwo jest zbudować dokumentację. Zainstaluj również [https://www.graphviz.org/ Graphviz], aby móc tworzyć diagramy pokazujące zależności pomiędzy różnymi klasami i bibliotekami w kodzie FreeCAD. Graphviz jest również używany przez [[Std_DependencyGraph/pl|wykres zależności]] programu FreeCAD do pokazywania zależności pomiędzy różnymi obiektami.
{{Code|code=
{{Code|code=
sudo apt install doxygen graphviz
sudo apt install doxygen graphviz
}}
}}


Then follow the same steps you would do to compile FreeCAD, as described on the [[Compile_on_Linux/Unix|compile on Unix]] page, and summarized here for convenience.
Następnie wykonaj te same kroki, które wykonałbyś, aby skompilować FreeCAD, jak opisano na stronie [[Compile_on_Linux/pl|kompilacja dla Linux]] i podsumowano tutaj dla wygody.
* Get the source code of FreeCAD and place it in its own directory {{incode|freecad-source}}.
* Pobierz kod źródłowy FreeCAD i umieść go we własnym katalogu {{incode|freecad-source}}.
* Create another directory {{incode|freecad-build}} in which you will compile FreeCAD and its documentation.
* Utwórz kolejny katalog {{incode|freecad-build}}, w którym skompilujesz FreeCAD i jego dokumentację.
* Skonfiguruj źródła za pomocą {{incode|cmake}}, upewniając się, że wskazujesz katalog źródłowy i określasz wymagane opcje kompilacji.
* Configure the sources with {{incode|cmake}}, making sure you indicate the source directory, and specify the required options for your build.
* Trigger the creation of the documentation using {{incode|make}}.
* Wyzwól tworzenie dokumentacji za pomocą {{incode|make}}.
{{Code|code=
{{Code|code=
git clone https://github.com/FreeCAD/FreeCAD.git freecad-source
git clone https://github.com/FreeCAD/FreeCAD.git freecad-source
Line 35: Line 43:
}}
}}


Gdy znajdujesz się w katalogu kompilacji, wydaj następującą instrukcję, aby utworzyć tylko dokumentację.
While you are inside the build directory issue the following instruction to create only the documentation.
{{Code|code=
{{Code|code=
make -j$(nproc --ignore=2) DevDoc
make -j$(nproc --ignore=2) DevDoc
}}
}}
As mentioned in [[Compiling (Speeding up)|compiling (speeding up)]], the {{incode|-j}} option sets the number of CPU cores used for compilation. The resulting documentation files will appear in the directory
Jak wspomniano na stronie [[Compiling_(Speeding up)/pl|Kompilacja (przyspieszamy)]], opcja {{incode|-j}} ustawia liczbę rdzeni procesora używanych do kompilacji. Wynikowe pliki dokumentacji pojawią się w katalogu
{{Code|code=
{{Code|code=
freecad-build/doc/SourceDocu/html/
freecad-build/doc/SourceDocu/html/
}}
}}


The point of entrance to the documentation is the {{incode|index.html}} file, which you can open with a web browser:
Punktem startowym dokumentacji jest plik {{incode|index.html}}, który można otworzyć za pomocą przeglądarki internetowej:
{{Code|code=
{{Code|code=
xdg-open freecad-build/doc/SourceDocu/html/index.html
xdg-open freecad-build/doc/SourceDocu/html/index.html
}}
}}


The {{incode|DevDoc}} target will generate a significant amount of data, around 5 GB of new files, particularly due to the diagrams created by Graphviz.
{{incode|DevDoc}} wygeneruje znaczną ilość danych, około 5 GB nowych plików, w szczególności ze względu na diagramy utworzone przez Graphviz.


<span id="Reduced_documentation"></span>
An alternative, smaller version of the documentation which takes only around 600 MB can be generated with a different target. This is the version displayed on the [http://www.freecadweb.org/api/ FreeCAD API website].
===Zredukowana dokumentacja===

Kompletna dokumentacja zajmuje około 3 GB miejsca na dysku. Alternatywna, mniejsza wersja dokumentacji, która zajmuje tylko około 600 MB, może być wygenerowana dla innych celów. Jest to wersja wyświetlana na stronie [https://freecad.github.io/SourceDoc/ FreeCAD API].
{{Code|code=
{{Code|code=
make -j$(nproc --ignore=2) WebDoc
make -j$(nproc --ignore=2) WebDoc
}}
}}


Dokumentacja na stronie [https://freecad.github.io/SourceDoc/ FreeCAD API] jest tworzona automatycznie z https://github.com/FreeCAD/SourceDoc . Każdy może ją przebudować i przesłać żądanie ściągnięcia ''(pull request)'':
== Other versions ==
[http://free-cad.sf.net/SrcDocu/index.html FreeCAD 0.12] documentation hosted in Sourceforge.


* wykonaj Fork repozytorium dla https://github.com/FreeCAD/SourceDoc
[https://iesensor.com/FreeCADDoc/0.16-dev/ FreeCAD 0.16 development] documentation built by [http://forum.freecadweb.org/viewtopic.php?t=12613 qingfeng.xia].
* na swoim komputerze: sklonuj kod FreeCAD (jeśli jeszcze tego nie zrobiłeś), utwórz katalog kompilacji dla dokumentu i sklonuj w nim powyższe repozytorium SourceDoc. Ten SourceDoc zostanie zaktualizowany po przebudowaniu dokumentu, a następnie będziesz mógł zatwierdzić i wypchnąć wyniki:
{{Code|code=
git clone https://github.com/FreeCAD/FreeCAD
cd FreeCAD
mkdir build
cd build
mkdir -p doc/SourceDocu/html
cd doc/SourceDocu/html
git clone your-fork-url
cd ../../..
cmake -DBUILD_QT5=ON -DPYTHON_EXECUTABLE=/usr/bin/python3 ..
make WebDoc
cd doc/SourceDocu/html
git commit
git push
}}
* Przejdź do swojego forka online i utwórz żądanie ściągnięcia.


==Inne wersje==
[https://iesensor.com/FreeCADDoc/0.19/ FreeCAD 0.19 development] documentation built by [http://forum.freecadweb.org/viewtopic.php?t=12613 qingfeng.xia].
[https://iesensor.com/FreeCADDoc/0.19/ FreeCAD 0.19 development] dokumentacja stworzona przez [http://forum.freecadweb.org/viewtopic.php?t=12613 qingfeng.xia].


<span id="Integrate_Coin3D_documentation"></span>
== Integrate Coin3D documentation ==
==Integracja dokumentacji Coin3D==


W systemach Unix możliwe jest połączenie dokumentacji źródłowej Coin3D z dokumentacją FreeCAD. Pozwala to na łatwiejszą nawigację i kompletne diagramy dziedziczenia dla klas pochodnych Coin.
On Unix systems it is possible to link Coin3D source documentation with FreeCAD's. This allows for easier navigation and complete inheritance diagrams for Coin derived classes.


*Install the {{incode|libcoin-doc}}, {{incode|libcoin80-doc}}, or similarly named package.
*Zainstaluj pakiet {{incode|libcoin-doc}}, {{incode|libcoin80-doc}} lub pakiet o podobnej nazwie.
*Unpack the archive {{incode|coin.tar.gz}} located in {{incode|/usr/share/doc/libcoin-doc/html}}; the files may be already unpacked in your system.
*Rozpakuj archiwum {{incode|coin.tar.gz}} znajdujące się w {{incode|/usr/share/doc/libcoin-doc/html}}, pliki mogą być już rozpakowane w twoim systemie.
*Wygeneruj ponownie dokumentację źródłową.
*Generate again the source documentation.


If you don't install the documentation package for Coin, the links will be generated to access the online documentation at [https://coin3d.bitbucket.io/Coin/ BitBucket]. This will happen if a Doxygen tag file can be downloaded at configure time with {{incode|wget}}.
Jeśli nie zainstalujesz pakietu dokumentacji dla Coin, zostaną wygenerowane linki umożliwiające dostęp do dokumentacji online na stronie [https://coin3d.bitbucket.io/Coin/ BitBucket]. Stanie się tak, jeśli plik znacznika Doxygen można pobrać w czasie konfiguracji za pomocą {{incode|wget}}.


<span id="Using_Doxygen"></span>
== Using Doxygen ==
==Wykorzystanie Doxygen==


See the [[Doxygen|Doxygen]] page for an extensive explanation on how to comment C++ and Python source code so that it can be processed by Doxygen to automatically create the documentation.
Zobacz stronę [[Doxygen/pl|Doxygen]], aby uzyskać obszerne wyjaśnienie, jak komentować kod źródłowy C++ i Python, aby mógł być przetwarzany przez Doxygen w celu automatycznego tworzenia dokumentacji.


Essentially, a comment block, starting with {{incode|/**}} or {{incode|///}} for C++, or {{incode|##}} for Python, needs to appear before every class or function definition, so that it is picked up by Doxygen. Many [[Doxygen#Doxygen markup|special commands]], which start with {{incode|\}} or {{incode|@}}, can be used to define parts of the code and format the output. [[Doxygen#Markdown support|Markdown syntax]] is also understood within the comment block, which makes it convenient to emphasize certain parts of the documentation.
Zasadniczo, blok komentarza, zaczynający się od {{incode|/**}} lub {{incode|///}} dla C++, lub {{incode|##}} dla Pythona, musi pojawić się przed każdą definicją klasy lub funkcji, tak aby został wychwycony przez Doxygen. Wiele [[Doxygen/pl#Znaczniki_Doxygen|specjalnych poleceń]], które zaczynają się od {{incode|\}} lub {{incode|@}}, może być użytych do zdefiniowania części kodu i sformatowania wyjścia. [[Doxygen/pl#Obsługa_znaczników_Markdown|Składnia Markdown]] jest również rozumiana w bloku komentarza, co sprawia, że wygodnie jest podkreślić pewne części dokumentacji.
{{Code|code=
{{Code|code=
/**
/**
Line 93: Line 123:
}}
}}


{{Docnav
|[[Extra python modules|Extra python modules]]
|[[List of Commands|List of Commands]]
}}


{{Docnav/pl
{{Userdocnavi}}
|[[Extra_python_modules/pl|Dodatkowe moduły Python]]
|[[Contributors/pl|Współtwórcy]]
}}


{{Userdocnavi{{#translation:}}}}
[[Category:Developer Documentation/pl]]
[[Category:Developer Documentation{{#translation:}}]]
{{clear}}
{{clear}}

Latest revision as of 06:23, 20 May 2023

Przegląd

Kod źródłowy FreeCAD jest komentowany, aby umożliwić automatyczne generowanie dokumentacji programistycznej przy użyciu narzędzia Doxygen, popularnego systemu dokumentacji kodu źródłowego. Doxygen może udokumentować zarówno C++ jak i Python będącego nieodzowną częścią FreeCAD, czego wynikiem są strony HTML z hiperłączami do każdej udokumentowanej funkcji i klasy.

Dokumentacja jest przechowywana online na stronie FreeCAD API. Proszę zauważyć, że ta dokumentacja może nie zawsze być aktualna. Jeśli potrzebujesz więcej szczegółów, pobierz najnowszy kod źródłowy FreeCAD i skompiluj dokumentację samodzielnie. Jeśli masz pilne pytania dotyczące kodu, zapytaj w sekcji dla deweloperów na forum FreeCAD.

Kompilacja dokumentacji API przebiega tak samo jak kompilacja pliku wykonywalnego programu FreeCAD, jak wskazano na stronie Kompilacja w Linux OS.

Ogólny przepływ pracy w celu skompilowania dokumentacji programistycznej programu FreeCAD. W systemie muszą znajdować się pakiety Doxygen i Graphviz, a także sam kod źródłowy FreeCAD. CMake konfiguruje system tak, aby za pomocą jednej instrukcji make dokumentacja całego projektu została skompilowana do wielu plików HTML z diagramami.

Zbuduj dokumentację źródłową

Pełna dokumentacja

Jeśli masz zainstalowany Doxygen, bardzo łatwo jest zbudować dokumentację. Zainstaluj również Graphviz, aby móc tworzyć diagramy pokazujące zależności pomiędzy różnymi klasami i bibliotekami w kodzie FreeCAD. Graphviz jest również używany przez wykres zależności programu FreeCAD do pokazywania zależności pomiędzy różnymi obiektami.

sudo apt install doxygen graphviz

Następnie wykonaj te same kroki, które wykonałbyś, aby skompilować FreeCAD, jak opisano na stronie kompilacja dla Linux i podsumowano tutaj dla wygody.

  • Pobierz kod źródłowy FreeCAD i umieść go we własnym katalogu freecad-source.
  • Utwórz kolejny katalog freecad-build, w którym skompilujesz FreeCAD i jego dokumentację.
  • Skonfiguruj źródła za pomocą cmake, upewniając się, że wskazujesz katalog źródłowy i określasz wymagane opcje kompilacji.
  • Wyzwól tworzenie dokumentacji za pomocą make.
git clone https://github.com/FreeCAD/FreeCAD.git freecad-source
mkdir freecad-build
cd freecad-build
cmake -DBUILD_QT5=ON -DPYTHON_EXECUTABLE=/usr/bin/python3 ../freecad-source

Gdy znajdujesz się w katalogu kompilacji, wydaj następującą instrukcję, aby utworzyć tylko dokumentację.

make -j$(nproc --ignore=2) DevDoc

Jak wspomniano na stronie Kompilacja (przyspieszamy), opcja -j ustawia liczbę rdzeni procesora używanych do kompilacji. Wynikowe pliki dokumentacji pojawią się w katalogu

freecad-build/doc/SourceDocu/html/

Punktem startowym dokumentacji jest plik index.html, który można otworzyć za pomocą przeglądarki internetowej:

xdg-open freecad-build/doc/SourceDocu/html/index.html

DevDoc wygeneruje znaczną ilość danych, około 5 GB nowych plików, w szczególności ze względu na diagramy utworzone przez Graphviz.

Zredukowana dokumentacja

Kompletna dokumentacja zajmuje około 3 GB miejsca na dysku. Alternatywna, mniejsza wersja dokumentacji, która zajmuje tylko około 600 MB, może być wygenerowana dla innych celów. Jest to wersja wyświetlana na stronie FreeCAD API.

make -j$(nproc --ignore=2) WebDoc

Dokumentacja na stronie FreeCAD API jest tworzona automatycznie z https://github.com/FreeCAD/SourceDoc . Każdy może ją przebudować i przesłać żądanie ściągnięcia (pull request):

  • wykonaj Fork repozytorium dla https://github.com/FreeCAD/SourceDoc
  • na swoim komputerze: sklonuj kod FreeCAD (jeśli jeszcze tego nie zrobiłeś), utwórz katalog kompilacji dla dokumentu i sklonuj w nim powyższe repozytorium SourceDoc. Ten SourceDoc zostanie zaktualizowany po przebudowaniu dokumentu, a następnie będziesz mógł zatwierdzić i wypchnąć wyniki:
git clone https://github.com/FreeCAD/FreeCAD
cd FreeCAD
mkdir build
cd build
mkdir -p doc/SourceDocu/html
cd doc/SourceDocu/html
git clone your-fork-url
cd ../../..
cmake -DBUILD_QT5=ON -DPYTHON_EXECUTABLE=/usr/bin/python3 ..
make WebDoc
cd doc/SourceDocu/html
git commit
git push
  • Przejdź do swojego forka online i utwórz żądanie ściągnięcia.

Inne wersje

FreeCAD 0.19 development dokumentacja stworzona przez qingfeng.xia.

Integracja dokumentacji Coin3D

W systemach Unix możliwe jest połączenie dokumentacji źródłowej Coin3D z dokumentacją FreeCAD. Pozwala to na łatwiejszą nawigację i kompletne diagramy dziedziczenia dla klas pochodnych Coin.

  • Zainstaluj pakiet libcoin-doc, libcoin80-doc lub pakiet o podobnej nazwie.
  • Rozpakuj archiwum coin.tar.gz znajdujące się w /usr/share/doc/libcoin-doc/html, pliki mogą być już rozpakowane w twoim systemie.
  • Wygeneruj ponownie dokumentację źródłową.

Jeśli nie zainstalujesz pakietu dokumentacji dla Coin, zostaną wygenerowane linki umożliwiające dostęp do dokumentacji online na stronie BitBucket. Stanie się tak, jeśli plik znacznika Doxygen można pobrać w czasie konfiguracji za pomocą wget.

Wykorzystanie Doxygen

Zobacz stronę Doxygen, aby uzyskać obszerne wyjaśnienie, jak komentować kod źródłowy C++ i Python, aby mógł być przetwarzany przez Doxygen w celu automatycznego tworzenia dokumentacji.

Zasadniczo, blok komentarza, zaczynający się od /** lub /// dla C++, lub ## dla Pythona, musi pojawić się przed każdą definicją klasy lub funkcji, tak aby został wychwycony przez Doxygen. Wiele specjalnych poleceń, które zaczynają się od \ lub @, może być użytych do zdefiniowania części kodu i sformatowania wyjścia. Składnia Markdown jest również rozumiana w bloku komentarza, co sprawia, że wygodnie jest podkreślić pewne części dokumentacji.

/**
 * Returns the name of the workbench object.
 */
std::string name() const;

/**
 * Set the name to the workbench object.
 */
void setName(const std::string&);

/// remove the added TaskWatcher
void removeTaskWatcher(void);