커널 문서에서 Sphinx 사용하기

Sphinx 기반 커널 문서 체계

이 페이지는 이탈리아어 번역 고지 `../disclaimer-ita.rst`를 포함하며 원래 영어 문서는 `Documentation/doc-guide/index.rst <doc_guide>`에서 확인하도록 안내합니다. 페이지 식별자는 `it_sphinxdoc`입니다.

리눅스 커널은 `Documentation` 디렉터리의 reStructuredText 파일을 Sphinx로 처리해 문서를 생성합니다. 소스 문서는 텍스트로 검토할 수 있고 여러 출력 형식으로 변환할 수 있습니다.

HTML은 `make htmldocs`, PDF는 `make pdfdocs`로 생성합니다. 결과는 `Documentation/output` 아래에 저장됩니다.

reStructuredText 파일은 소스 코드의 문서 주석과 kernel-doc 주석을 포함하는 지시문을 사용할 수 있습니다. 이런 주석은 함수, 자료형, 코드 구조와 설계를 설명합니다.

kernel-doc 주석은 특별한 구조와 형식을 갖지만 추출된 본문은 reStructuredText로 처리됩니다. 따라서 API 주석에서도 문단, 참조, 목록 같은 ReST 기능을 활용할 수 있습니다.

`Documentation`에는 아직 일반 텍스트 형식인 문서도 수천 개 있습니다. 일부는 시간이 지나며 reStructuredText로 변환되겠지만 모든 문서를 형식 변경 대상으로 보지는 않습니다.

.. include:: ../disclaimer-ita.rst

.. note:: Per leggere la documentazione originale in inglese:
	  :ref:`Documentation/doc-guide/index.rst <doc_guide>`

.. _it_sphinxdoc:

=============================================
Usare Sphinx per la documentazione del kernel
=============================================

Il kernel Linux usa `Sphinx`_ per la generazione della documentazione a partire
dai file `reStructuredText`_ che si trovano nella cartella ``Documentation``.
Per generare la documentazione in HTML o PDF, usate comandi ``make htmldocs`` o
``make pdfdocs``. La documentazione così generata sarà disponibile nella
cartella ``Documentation/output``.

.. _Sphinx: http://www.sphinx-doc.org/
.. _reStructuredText: http://docutils.sourceforge.net/rst.html

I file reStructuredText possono contenere delle direttive che permettono di
includere i commenti di documentazione, o di tipo kernel-doc, dai file
sorgenti.
Solitamente questi commenti sono utilizzati per descrivere le funzioni, i tipi
e l'architettura del codice. I commenti di tipo kernel-doc hanno una struttura
e formato speciale, ma a parte questo vengono processati come reStructuredText.

Inoltre, ci sono migliaia di altri documenti in formato testo sparsi nella
cartella ``Documentation``. Alcuni di questi verranno probabilmente convertiti,
nel tempo, in formato reStructuredText, ma la maggior parte di questi rimarranno
in formato testo.

Sphinx 설치와 가상환경

`Documentation/`의 ReST 표식은 Sphinx 1.7 이상에서 처리하도록 작성됐습니다. 실제 요구 사항은 `sphinx-pre-install` 검사 스크립트로 확인할 수 있습니다.

대부분의 리눅스 배포판이 Sphinx를 제공하지만 Sphinx와 Python 라이브러리 조합은 버전 변화에 민감합니다. 패키지 하나를 갱신한 뒤 문서 생성이 깨지는 상황도 드물지 않습니다.

배포판 패키지와 분리하려면 Python 3용 `virtualenv-3` 또는 `virtualenv`로 전용 가상환경을 만듭니다. 문서 도구 버전을 프로젝트 단위로 고정해 시스템 Python의 변화를 피할 수 있습니다.

HTML에는 Read the Docs 테마 사용을 권장합니다. Sphinx 버전에 따라 `pip install sphinx_rtd_theme`로 테마를 별도 설치해야 할 수 있습니다.

일부 ReST 페이지의 수식은 LaTeX로 작성됩니다. 수식을 제대로 해석하려면 `texlive`와 `amdfonts`, `amsmath` 패키지가 필요합니다.

예시는 `sphinx_2.4.4` 가상환경을 만든 뒤 활성화하고 `Documentation/sphinx/requirements.txt`의 패키지를 설치합니다. 요구 사항 파일이 호환되는 문서 도구 묶음을 정의합니다.

가상환경을 활성화하면 셸 프롬프트가 바뀝니다. 새 셸 세션에서는 문서를 빌드하기 전에 `. sphinx_2.4.4/bin/activate`를 다시 실행해야 합니다.

가상환경 이름에 Sphinx 버전을 넣으면 여러 문서 도구 조합을 나란히 유지하고 비교하기 쉽습니다. 빌드 실패가 소스 변경 때문인지 도구 버전 때문인지 분리해 확인할 때도 도움이 됩니다.

Riassumendo, se volete installare la versione 2.4.4 di Sphinx dovete eseguire::

       $ virtualenv sphinx_2.4.4
       $ . sphinx_2.4.4/bin/activate
       (sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txt

Dopo aver eseguito ``. sphinx_2.4.4/bin/activate``, il prompt cambierà per
indicare che state usando il nuovo ambiente. Se aprite un nuova sessione,
prima di generare la documentazione, dovrete rieseguire questo comando per
rientrare nell'ambiente virtuale.

.. _it_sphinx_install:

Installazione Sphinx
====================

I marcatori ReST utilizzati nei file in Documentation/ sono pensati per essere
processati da ``Sphinx`` nella versione 1.7 o superiore.

Esiste uno script che verifica i requisiti Sphinx. Per ulteriori dettagli
consultate :ref:`it_sphinx-pre-install`.

La maggior parte delle distribuzioni Linux forniscono Sphinx, ma l'insieme dei
programmi e librerie è fragile e non è raro che dopo un aggiornamento di
Sphinx, o qualche altro pacchetto Python, la documentazione non venga più
generata correttamente.

Un modo per evitare questo genere di problemi è quello di utilizzare una
versione diversa da quella fornita dalla vostra distribuzione. Per fare questo,
vi raccomandiamo di installare Sphinx dentro ad un ambiente virtuale usando
``virtualenv-3`` o ``virtualenv`` a seconda di come Python 3 è stato
pacchettizzato dalla vostra distribuzione.

.. note::

   #) Viene raccomandato l'uso del tema RTD per la documentazione in HTML.
      A seconda della versione di Sphinx, potrebbe essere necessaria
      l'installazione tramite il comando ``pip install sphinx_rtd_theme``.

   #) Alcune pagine ReST contengono delle formule matematiche. A causa del
      modo in cui Sphinx funziona, queste espressioni sono scritte
      utilizzando LaTeX. Per una corretta interpretazione, è necessario aver
      installato texlive con i pacchetti amdfonts e amsmath.

Riassumendo, se volete installare la versione 2.4.4 di Sphinx dovete eseguire::

       $ virtualenv sphinx_2.4.4
       $ . sphinx_2.4.4/bin/activate
       (sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txt

Dopo aver eseguito ``. sphinx_2.4.4/bin/activate``, il prompt cambierà per
indicare che state usando il nuovo ambiente. Se aprite un nuova sessione,
prima di generare la documentazione, dovrete rieseguire questo comando per
rientrare nell'ambiente virtuale.

이미지·PDF 의존성과 사전 검사

커널 문서 생성 체계에는 Graphviz와 SVG 이미지를 처리하는 확장이 있습니다. 관련 동작은 뒤의 `it_sphinx_kfigure` 절에서 설명합니다.

이미지 생성을 위해 Graphviz와 ImageMagick을 모두 설치해야 합니다. 패키지가 없어도 문서 빌드는 계속될 수 있지만 최종 문서에서 이미지가 빠집니다.

PDF와 LaTeX 출력은 이 문서 기준으로 Sphinx 2.4보다 높은 버전에서 지원됩니다. 해당 출력에는 버전 3.14159265의 `XeLaTeX`도 필요합니다.

배포판에 따라 XeLaTeX가 작동하는 데 필요한 최소 `texlive` 패키지 묶음을 추가로 설치해야 합니다. HTML만 빌드할 때보다 PDF 도구 체인의 의존성이 큽니다.

`./scripts/sphinx-pre-install`은 현재 배포판을 감지해 필요한 도구를 검사하고 설치 명령을 제안합니다. 예시는 Fedora 26에서 누락된 `texlive-luatex85`와 가상환경 설정을 알려줍니다.

기본 검사는 HTML과 PDF, 이미지, 수식, LaTeX 지원을 함께 확인하고 Python 가상환경 사용을 가정합니다. HTML 요구 사항은 필수이고 나머지는 선택 요구 사항으로 분류됩니다.

`--no-pdf`는 PDF 생성 관련 검사를 끕니다. HTML 문서만 필요한 환경에서 불필요한 TeX 의존성 경고를 피할 수 있습니다.

`--no-virtualenv`는 Python 가상환경 대신 운영체제의 기본 환경을 검사합니다. 배포판 패키지로 문서 도구를 관리할 때 사용합니다.

	$ ./scripts/sphinx-pre-install
	Checking if the needed tools for Fedora release 26 (Twenty Six) are available
	Warning: better to also install "texlive-luatex85".
	You should run:

		sudo dnf install -y texlive-luatex85
		/usr/bin/virtualenv sphinx_2.4.4
		. sphinx_2.4.4/bin/activate
		pip install -r Documentation/sphinx/requirements.txt

	Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.

Generazione d'immagini
----------------------

Il meccanismo che genera la documentazione del kernel contiene un'estensione
capace di gestire immagini in formato Graphviz e SVG (per maggior informazioni
vedere :ref:`it_sphinx_kfigure`).

Per far si che questo funzioni, dovete installare entrambe i pacchetti
Graphviz e ImageMagick. Il sistema di generazione della documentazione è in
grado di procedere anche se questi pacchetti non sono installati, ma il
risultato, ovviamente, non includerà le immagini.

Generazione in PDF e LaTeX
--------------------------

Al momento, la generazione di questi documenti è supportata solo dalle
versioni di Sphinx superiori alla 2.4.

Per la generazione di PDF e LaTeX, avrete bisogno anche del pacchetto
``XeLaTeX`` nella versione 3.14159265

Per alcune distribuzioni Linux potrebbe essere necessario installare
anche una serie di pacchetti ``texlive`` in modo da fornire il supporto
minimo per il funzionamento di ``XeLaTeX``.

.. _it_sphinx-pre-install:

Verificare le dipendenze Sphinx
-------------------------------

Esiste uno script che permette di verificare automaticamente le dipendenze di
Sphinx. Se lo script riesce a riconoscere la vostra distribuzione, allora
sarà in grado di darvi dei suggerimenti su come procedere per completare
l'installazione::

	$ ./scripts/sphinx-pre-install
	Checking if the needed tools for Fedora release 26 (Twenty Six) are available
	Warning: better to also install "texlive-luatex85".
	You should run:

		sudo dnf install -y texlive-luatex85
		/usr/bin/virtualenv sphinx_2.4.4
		. sphinx_2.4.4/bin/activate
		pip install -r Documentation/sphinx/requirements.txt

	Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.

L'impostazione predefinita prevede il controllo dei requisiti per la generazione
di documenti html e PDF, includendo anche il supporto per le immagini, le
espressioni matematiche e LaTeX; inoltre, presume che venga utilizzato un
ambiente virtuale per Python. I requisiti per generare i documenti html
sono considerati obbligatori, gli altri sono opzionali.

Questo script ha i seguenti parametri:

``--no-pdf``
	Disabilita i controlli per la generazione di PDF;

``--no-virtualenv``
	Utilizza l'ambiente predefinito dal sistema operativo invece che
	l'ambiente virtuale per Python;

Sphinx 문서 빌드와 범위 제어

HTML과 PDF는 각각 `make htmldocs`와 `make pdfdocs`로 생성합니다. 다른 출력 형식과 빌드 대상은 `make help`에서 확인할 수 있습니다.

생성 결과는 `Documentation/output`에 놓입니다. 빌드 프로그램인 `sphinx-build`가 설치돼 있어야 하며, 사용 가능하면 HTML에 Read the Docs 테마를 적용합니다.

PDF에는 XeLaTeX와 ImageMagick의 `convert(1)`가 필요합니다. `inkscape(1)`를 설치하면 특히 커널 5.18 이상 문서를 PDF로 만들 때 포함 이미지의 품질이 좋아질 수 있습니다.

Sphinx에 추가 옵션을 전달할 때는 make 변수 `SPHINXOPTS`를 사용합니다. `make SPHINXOPTS=-v htmldocs`는 상세 출력을 켠 HTML 빌드입니다.

HTML 출력에 추가 CSS 계층을 적용하려면 환경 변수 `DOCS_CSS`를 사용합니다. 문서 내용과 별개로 사이트 표시를 맞출 때 쓰는 선택 지점입니다.

일부 문서만 만들려면 `SPHINXDIRS`를 지정합니다. `make SPHINXDIRS=doc-guide htmldocs`는 `Documentation/doc-guide` 하위 문서만 생성합니다.

지정 가능한 하위 디렉터리는 `make help`의 문서 절에서 확인합니다. 부분 빌드는 변경한 영역의 경고를 빠르게 확인하는 데 유용합니다.

생성된 문서를 지우려면 `make cleandocs`를 실행합니다. 오래된 산출물이 새 결과와 섞였다고 의심될 때 깨끗한 상태에서 다시 빌드할 수 있습니다.

부분 빌드는 빠른 반복에 유리하지만 다른 문서에서 들어오는 교차 참조와 최상위 인덱스 문제를 모두 드러내지는 못할 수 있습니다. 제출 전에는 변경 범위에 맞춰 전체 HTML 빌드도 확인해야 합니다.

Per generare la documentazione in formato HTML o PDF si eseguono i rispettivi
comandi ``make htmldocs`` o ``make pdfdocs``. Esistono anche altri formati
in cui è possibile generare la documentazione; per maggiori informazioni
potere eseguire il comando ``make help``.
La documentazione così generata sarà disponibile nella sottocartella
``Documentation/output``.

Ovviamente, per generare la documentazione, Sphinx (``sphinx-build``)
dev'essere installato. Se disponibile, il tema *Read the Docs* per Sphinx
verrà utilizzato per ottenere una documentazione HTML più gradevole.
Per la documentazione in formato PDF, invece, avrete bisogno di ``XeLaTeX`
e di ``convert(1)`` disponibile in ImageMagick
(https://www.imagemagick.org). \ [#ink]_
Tipicamente, tutti questi pacchetti sono disponibili e pacchettizzati nelle
distribuzioni Linux.

Per poter passare ulteriori opzioni a Sphinx potete utilizzare la variabile
make ``SPHINXOPTS``. Per esempio, se volete che Sphinx sia più verboso durante
la generazione potete usare il seguente comando ``make SPHINXOPTS=-v htmldocs``.

Potete anche personalizzare l'ouptut html passando un livello aggiuntivo
DOCS_CSS usando la rispettiva variabile d'ambiente ``DOCS_CSS``.

La variable make ``SPHINXDIRS`` è utile quando si vuole generare solo una parte
della documentazione. Per esempio, si possono generare solo di documenti in
``Documentation/doc-guide`` eseguendo ``make SPHINXDIRS=doc-guide htmldocs``. La
sezione dedicata alla documentazione di ``make help`` vi mostrerà quali sotto
cartelle potete specificare.

Potete eliminare la documentazione generata tramite il comando
``make cleandocs``.

Generazione della documentazione Sphinx
=======================================

Per generare la documentazione in formato HTML o PDF si eseguono i rispettivi
comandi ``make htmldocs`` o ``make pdfdocs``. Esistono anche altri formati
in cui è possibile generare la documentazione; per maggiori informazioni
potere eseguire il comando ``make help``.
La documentazione così generata sarà disponibile nella sottocartella
``Documentation/output``.

Ovviamente, per generare la documentazione, Sphinx (``sphinx-build``)
dev'essere installato. Se disponibile, il tema *Read the Docs* per Sphinx
verrà utilizzato per ottenere una documentazione HTML più gradevole.
Per la documentazione in formato PDF, invece, avrete bisogno di ``XeLaTeX`
e di ``convert(1)`` disponibile in ImageMagick
(https://www.imagemagick.org). \ [#ink]_
Tipicamente, tutti questi pacchetti sono disponibili e pacchettizzati nelle
distribuzioni Linux.

Per poter passare ulteriori opzioni a Sphinx potete utilizzare la variabile
make ``SPHINXOPTS``. Per esempio, se volete che Sphinx sia più verboso durante
la generazione potete usare il seguente comando ``make SPHINXOPTS=-v htmldocs``.

Potete anche personalizzare l'ouptut html passando un livello aggiuntivo
DOCS_CSS usando la rispettiva variabile d'ambiente ``DOCS_CSS``.

La variable make ``SPHINXDIRS`` è utile quando si vuole generare solo una parte
della documentazione. Per esempio, si possono generare solo di documenti in
``Documentation/doc-guide`` eseguendo ``make SPHINXDIRS=doc-guide htmldocs``. La
sezione dedicata alla documentazione di ``make help`` vi mostrerà quali sotto
cartelle potete specificare.

Potete eliminare la documentazione generata tramite il comando
``make cleandocs``.

.. [#ink] Avere installato anche ``inkscape(1)`` dal progetto Inkscape ()
          potrebbe aumentare la qualità delle immagini che verranno integrate
          nel documento PDF, specialmente per quando si usando rilasci del
          kernel uguali o superiori a 5.18

새 문서 추가와 문서 트리 구성

새 문서를 추가하는 기본 절차는 간단합니다. `Documentation`의 적절한 하위 디렉터리에 `.rst` 파일을 만들고 `Documentation/index.rst`의 TOC tree에 참조를 추가합니다.

짧고 독립적인 문서는 이 두 단계만으로 충분합니다. 문서가 복잡하거나 여러 파일로 나뉘면 전용 하위 디렉터리와 그 안의 `index.rst`를 사용하는 편이 좋습니다.

이미 적절한 하위 디렉터리가 있다면 새 디렉터리를 만들기보다 기존 분류에 넣습니다. 독자가 하위 시스템별 문서를 예측 가능한 위치에서 찾게 하기 위함입니다.

그래픽 하위 시스템은 `Documentation/gpu` 아래 여러 `.rst` 파일과 전용 `index.rst`, 전용 `toctree`를 두고 그 인덱스를 최상위 인덱스에서 참조하는 예입니다.

Sphinx와 reStructuredText의 전체 기능은 각 공식 문서를 참고합니다. 처음에는 Sphinx의 reStructuredText 입문서가 적합하고, 필요할 때 Sphinx 전용 구성 요소를 확인합니다.

Scrivere la documentazione
==========================

Aggiungere nuova documentazione è semplice:

1. aggiungete un file ``.rst`` nella sottocartella ``Documentation``
2. aggiungete un riferimento ad esso nell'indice (`TOC tree`_) in
   ``Documentation/index.rst``.

.. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html

Questo, di solito, è sufficiente per la documentazione più semplice (come
quella che state leggendo ora), ma per una documentazione più elaborata è
consigliato creare una sottocartella dedicata (o, quando possibile, utilizzarne
una già esistente). Per esempio, il sottosistema grafico è documentato nella
sottocartella ``Documentation/gpu``; questa documentazione è divisa in
diversi file ``.rst`` ed un indice ``index.rst`` (con un ``toctree``
dedicato) a cui si fa riferimento nell'indice principale.

Consultate la documentazione di `Sphinx`_ e `reStructuredText`_ per maggiori
informazione circa le loro potenzialità. In particolare, il
`manuale introduttivo a reStructuredText`_ di Sphinx è un buon punto da
cui cominciare. Esistono, inoltre, anche alcuni
`costruttori specifici per Sphinx`_.

.. _`manuale introduttivo a reStructuredText`: http://www.sphinx-doc.org/en/stable/rest.html
.. _`costruttori specifici per Sphinx`: http://www.sphinx-doc.org/en/stable/markup/index.html

커널 문서 작성 지침

커널 문서에서는 reStructuredText 구조를 과도하게 사용하지 않습니다. 대부분의 내용은 최소한의 구조만 가진 단순 텍스트여야 여러 출력 형식과 소스 직접 읽기에 모두 적합합니다.

기존 텍스트 문서를 ReST로 바꿀 때 원래 구조를 가능한 한 충실하게 유지합니다. 형식 변환 때문에 정보의 순서와 강조 체계가 불필요하게 달라지지 않게 합니다.

변환 작업은 표식만 바꾸는 데 그치지 않고 오래된 내용도 함께 갱신해야 합니다. 형식이 현대화됐는데 기술 설명은 낡은 상태로 남는 결과를 피합니다.

문서 제목은 위아래에 `=` 줄을 두고, 장은 아래에 `=`, 절은 아래에 `-`, 하위 절은 아래에 `~`를 둡니다. ReST 자체가 고정 순서를 강제하지 않아도 커널 문서에서는 이 관례를 지킵니다.

일관된 머리말 장식은 소스만 읽을 때도 계층을 빠르게 파악하게 하고, 여러 작성자가 만든 문서가 같은 구조로 보이게 합니다.

구문 강조가 필요 없는 짧은 고정폭 블록은 `::`를 사용합니다. 짧은 명령 출력이나 작은 예제에 적합합니다.

긴 코드이거나 언어별 구문 강조가 도움이 되면 `.. code-block:: <language>`를 사용합니다. 본문 안의 짧은 코드 조각은 이중 백틱으로 감쌉니다.

* Mantenete la decorazione dei livelli di intestazione come segue:

  1. ``=`` con una linea superiore per il titolo del documento::

       ======
       Titolo
       ======

  2. ``=`` per i capitoli::

       Capitoli
       ========

  3. ``-`` per le sezioni::

       Sezioni
       -------

  4. ``~`` per le sottosezioni::

       Sottosezioni
       ~~~~~~~~~~~~

  Sebbene RST non forzi alcun ordine specifico (*Piuttosto che imporre
  un numero ed un ordine fisso di decorazioni, l'ordine utilizzato sarà
  quello incontrato*), avere uniformità dei livelli principali rende più
  semplice la lettura dei documenti.

* Per inserire blocchi di testo con caratteri a dimensione fissa (codici di
  esempio, casi d'uso, eccetera): utilizzate ``::`` quando non è necessario
  evidenziare la sintassi, specialmente per piccoli frammenti; invece,
  utilizzate ``.. code-block:: <language>`` per blocchi più lunghi che
  beneficeranno della sintassi evidenziata. Per un breve pezzo di codice da
  inserire nel testo, usate \`\`.

Guide linea per la documentazione del kernel
--------------------------------------------

In questa sezione troverete alcune linee guida specifiche per la documentazione
del kernel:

* Non esagerate con i costrutti di reStructuredText. Mantenete la
  documentazione semplice. La maggior parte della documentazione dovrebbe
  essere testo semplice con una strutturazione minima che permetta la
  conversione in diversi formati.

* Mantenete la strutturazione il più fedele possibile all'originale quando
  convertite un documento in formato reStructuredText.

* Aggiornate i contenuti quando convertite della documentazione, non limitatevi
  solo alla formattazione.

* Mantenete la decorazione dei livelli di intestazione come segue:

  1. ``=`` con una linea superiore per il titolo del documento::

       ======
       Titolo
       ======

  2. ``=`` per i capitoli::

       Capitoli
       ========

  3. ``-`` per le sezioni::

       Sezioni
       -------

  4. ``~`` per le sottosezioni::

       Sottosezioni
       ~~~~~~~~~~~~

  Sebbene RST non forzi alcun ordine specifico (*Piuttosto che imporre
  un numero ed un ordine fisso di decorazioni, l'ordine utilizzato sarà
  quello incontrato*), avere uniformità dei livelli principali rende più
  semplice la lettura dei documenti.

* Per inserire blocchi di testo con caratteri a dimensione fissa (codici di
  esempio, casi d'uso, eccetera): utilizzate ``::`` quando non è necessario
  evidenziare la sintassi, specialmente per piccoli frammenti; invece,
  utilizzate ``.. code-block:: <language>`` per blocchi più lunghi che
  beneficeranno della sintassi evidenziata. Per un breve pezzo di codice da
  inserire nel testo, usate \`\`.

Sphinx C domain과 함수 참조

Sphinx의 C domain인 `c`는 C API 문서화에 맞춘 지시문과 참조를 제공합니다. 함수 원형은 `.. c:function::` 지시문으로 선언할 수 있습니다.

예제 `.. c:function:: int ioctl( int fd, int request )`는 함수 이름, 반환형, 매개변수를 C domain 객체로 등록합니다.

커널 문서의 C domain 확장은 흔한 함수 이름에 별도 참조 이름을 줄 수 있습니다. `ioctl`처럼 여러 곳에서 쓰는 이름에는 `:name: VIDIOC_LOG_STATUS`를 지정할 수 있습니다.

함수 원형의 표시 이름 `ioctl`은 그대로 유지되지만 참조 대상 이름과 인덱스 항목은 `VIDIOC_LOG_STATUS`로 바뀝니다. 독자는 문맥에 맞는 고유 API 항목으로 이동합니다.

함수 참조를 만들기 위해 일반적으로 `c:func:` 역할을 직접 쓸 필요가 없습니다. 커널 문서 확장이 `function()` 형태의 텍스트를 인덱스의 함수 항목과 자동으로 교차 연결합니다.

기존 커널 문서에서 불필요한 `c:func:`를 발견하면 단순한 `function()` 표기로 바꿀 수 있습니다. 소스 가독성을 높이면서 생성 링크는 유지됩니다.

.. code-block:: rst

    .. c:function:: int ioctl( int fd, int request )

Il dominio C per kernel-doc ha delle funzionalità aggiuntive. Per esempio,
potete assegnare un nuovo nome di riferimento ad una funzione con un nome
molto comune come ``open`` o ``ioctl``:

.. code-block:: rst

     .. c:function:: int ioctl( int fd, int request )
        :name: VIDIOC_LOG_STATUS

Il nome della funzione (per esempio ioctl) rimane nel testo ma il nome del suo
riferimento cambia da ``ioctl`` a ``VIDIOC_LOG_STATUS``. Anche la voce
nell'indice cambia in ``VIDIOC_LOG_STATUS``.

Notate che per una funzione non c'è bisogno di usare ``c:func:`` per generarne
i riferimenti nella documentazione. Grazie a qualche magica estensione a
Sphinx, il sistema di generazione della documentazione trasformerà
automaticamente un riferimento ad una ``funzione()`` in un riferimento
incrociato quando questa ha una voce nell'indice.  Se trovate degli usi di
``c:func:`` nella documentazione del kernel, sentitevi liberi di rimuoverli.

Il dominio C
------------

Il **Dominio Sphinx C** (denominato c) è adatto alla documentazione delle API C.
Per esempio, un prototipo di una funzione:

.. code-block:: rst

    .. c:function:: int ioctl( int fd, int request )

Il dominio C per kernel-doc ha delle funzionalità aggiuntive. Per esempio,
potete assegnare un nuovo nome di riferimento ad una funzione con un nome
molto comune come ``open`` o ``ioctl``:

.. code-block:: rst

     .. c:function:: int ioctl( int fd, int request )
        :name: VIDIOC_LOG_STATUS

Il nome della funzione (per esempio ioctl) rimane nel testo ma il nome del suo
riferimento cambia da ``ioctl`` a ``VIDIOC_LOG_STATUS``. Anche la voce
nell'indice cambia in ``VIDIOC_LOG_STATUS``.

Notate che per una funzione non c'è bisogno di usare ``c:func:`` per generarne
i riferimenti nella documentazione. Grazie a qualche magica estensione a
Sphinx, il sistema di generazione della documentazione trasformerà
automaticamente un riferimento ad una ``funzione()`` in un riferimento
incrociato quando questa ha una voce nell'indice.  Se trovate degli usi di
``c:func:`` nella documentazione del kernel, sentitevi liberi di rimuoverli.

list-table과 flat-table

`list-table`은 Sphinx의 ASCII 표 형식으로 쓰기 어려운 표를 표현할 수 있습니다. 하지만 원본 텍스트를 직접 읽는 사람에게는 구조가 잘 보이지 않으므로 강한 이유가 없으면 피합니다.

`flat-table`도 목록의 목록으로 표를 작성하지만 셀 병합과 누락 셀 처리 같은 추가 기능을 제공합니다.

`:cspan:` 역할은 현재 셀을 뒤의 여러 열로 확장하고 `:rspan:`은 뒤의 여러 행으로 확장합니다. 값은 추가로 차지할 열 또는 행의 수입니다.

기본 auto-span은 행 오른쪽의 셀이 부족할 때 마지막 셀을 오른쪽으로 확장합니다. `:fill-cells:`를 주면 확장 대신 빈 셀을 자동으로 채웁니다.

`:header-rows:`는 머리글 행 수, `:stub-columns:`는 행 머리 역할의 열 수, `:widths:`는 각 열 너비를 지정합니다.

flat-table의 첫 목록 단계는 행이고, 행 안에는 셀 목록만 둡니다. 예외적으로 `..` 주석과 참조 대상 같은 링크 표식을 행 구조에 넣을 수 있습니다.

예제는 네 열을 만들고 첫 행을 머리글처럼 배치합니다. 첫 데이터 행의 마지막 셀은 auto-span으로 남은 열을 차지합니다.

둘째 데이터 행의 `:rspan:`1` :cspan:`1`` 셀은 두 행과 두 열에 걸칩니다. 마지막 행에는 `it last row` 참조 대상을 두고 첫 셀만 제공합니다.

문서의 다음 블록은 같은 flat-table을 실제로 렌더링합니다. 표를 작성할 때 소스 구조와 생성된 셀 병합 결과를 함께 확인해야 합니다.

셀 병합 기능이 필요하지 않은 단순 표라면 소스에서 바로 읽을 수 있는 일반 표가 더 낫습니다. `flat-table`은 복잡한 배치를 표현하는 이점이 소스 가독성 저하보다 클 때 선택합니다.

.. code-block:: rst

   .. flat-table:: table title
      :widths: 2 1 1 3

      * - head col 1
        - head col 2
        - head col 3
        - head col 4

      * - row 1
        - field 1.1
        - field 1.2 with autospan

      * - row 2
        - field 2.1
        - :rspan:`1` :cspan:`1` field 2.2 - 3.3

      * .. _`it last row`:

        - row 3

Tabelle a liste
---------------

Il formato ``list-table`` può essere utile per tutte quelle tabelle che non
possono essere facilmente scritte usando il formato ASCII-art di Sphinx. Però,
questo genere di tabelle sono illeggibili per chi legge direttamente i file di
testo. Dunque, questo formato dovrebbe essere evitato senza forti argomenti che
ne giustifichino l'uso.

La ``flat-table`` è anch'essa una lista di liste simile alle ``list-table``
ma con delle funzionalità aggiuntive:

* column-span: col ruolo ``cspan`` una cella può essere estesa attraverso
  colonne successive

* raw-span: col ruolo ``rspan`` una cella può essere estesa attraverso
  righe successive

* auto-span: la cella più a destra viene estesa verso destra per compensare
  la mancanza di celle. Con l'opzione ``:fill-cells:`` questo comportamento
  può essere cambiato da *auto-span* ad *auto-fill*, il quale inserisce
  automaticamente celle (vuote) invece che estendere l'ultima.

opzioni:

* ``:header-rows:``   [int] conta le righe di intestazione
* ``:stub-columns:``  [int] conta le colonne di stub
* ``:widths:``        [[int] [int] ... ] larghezza delle colonne
* ``:fill-cells:``    invece di estendere automaticamente una cella su quelle
  mancanti, ne crea di vuote.

ruoli:

* ``:cspan:`` [int] colonne successive (*morecols*)
* ``:rspan:`` [int] righe successive (*morerows*)

L'esempio successivo mostra come usare questo marcatore. Il primo livello della
nostra lista di liste è la *riga*. In una *riga* è possibile inserire solamente
la lista di celle che compongono la *riga* stessa. Fanno eccezione i *commenti*
( ``..`` ) ed i *collegamenti* (per esempio, un riferimento a
``:ref:`last row <last row>``` / :ref:`last row <it last row>`)

.. code-block:: rst

   .. flat-table:: table title
      :widths: 2 1 1 3

      * - head col 1
        - head col 2
        - head col 3
        - head col 4

      * - row 1
        - field 1.1
        - field 1.2 with autospan

      * - row 2
        - field 2.1
        - :rspan:`1` :cspan:`1` field 2.2 - 3.3

      * .. _`it last row`:

        - row 3

Che verrà rappresentata nel seguente modo:

   .. flat-table:: table title
      :widths: 2 1 1 3

      * - head col 1
        - head col 2
        - head col 3
        - head col 4

      * - row 1
        - field 1.1
        - field 1.2 with autospan

      * - row 2
        - field 2.1
        - :rspan:`1` :cspan:`1` field 2.2 - 3.3

      * .. _`it last row`:

        - row 3

문서 간 교차 참조

한 문서에서 다른 문서로 연결할 때는 해당 파일 경로를 그대로 적을 수 있으며 특별한 구문이 필요하지 않습니다. 절대 경로와 상대 경로를 모두 지원합니다.

절대 경로는 `Documentation/`으로 시작합니다. 어느 문서에서 읽어도 같은 대상을 가리키므로 이동에 강합니다.

같은 디렉터리나 상위 디렉터리의 문서는 `sphinx.rst`, `../sphinx.rst` 같은 상대 경로로 참조할 수 있습니다. 이 방식에서도 `.rst` 확장자가 필요합니다.

링크에 문서 제목과 다른 표시 문구가 필요하면 Sphinx의 `doc` 역할을 사용해 `:doc:`내 링크 문구 <sphinx>``처럼 작성합니다.

대부분은 파일 경로를 직접 쓰는 방식이 더 단순하고 소스 독자에게도 명확합니다. 표시 문구가 없는 `:doc:` 참조는 경로 표기로 바꾸는 것이 권장됩니다.

함수나 자료형의 kernel-doc 교차 참조는 별도의 kernel-doc 지침을 따릅니다. 이 절은 문서 페이지 사이의 연결 방식에 초점을 둡니다.

    Vedere Documentation/doc-guide/sphinx.rst. Questo funziona sempre
    Guardate pshinx.rst, che si trova nella stessa cartella.
    Leggete ../sphinx.rst, che si trova nella cartella precedente.

Se volete che il collegamento abbia un testo diverso rispetto al
titolo del documento, allora dovrete usare la direttiva Sphinx
``doc``. Per esempio::

    Vedere :doc:`il mio testo per il collegamento <sphinx>`.

Riferimenti incrociati
----------------------

Aggiungere un riferimento incrociato da una pagina della
documentazione ad un'altra può essere fatto scrivendo il percorso al
file corrispondende, non serve alcuna sintassi speciale. Si possono
usare sia percorsi assoluti che relativi. Quelli assoluti iniziano con
"documentation/". Per esempio, potete fare riferimento a questo
documento in uno dei seguenti modi (da notare che l'estensione
``.rst`` è necessaria)::

    Vedere Documentation/doc-guide/sphinx.rst. Questo funziona sempre
    Guardate pshinx.rst, che si trova nella stessa cartella.
    Leggete ../sphinx.rst, che si trova nella cartella precedente.

Se volete che il collegamento abbia un testo diverso rispetto al
titolo del documento, allora dovrete usare la direttiva Sphinx
``doc``. Per esempio::

    Vedere :doc:`il mio testo per il collegamento <sphinx>`.

Nella maggioranza dei casi si consiglia il primo metodo perché è più
pulito ed adatto a chi legge dai sorgenti. Se incontrare un ``:doc:``
che non da alcun valore, sentitevi liberi di convertirlo in un
percorso al documento.

Per informazioni riguardo ai riferimenti incrociati ai commenti
kernel-doc per funzioni o tipi, consultate

kernel-figure와 DOT 이미지

이미지를 추가할 때는 커널 전용 `kernel-figure`와 `kernel-image` 지시문을 사용합니다. 두 지시문은 문서 빌드 환경에 맞춰 이미지 처리와 대체 출력을 관리합니다.

SVG 예제는 `../../../doc-guide/svg_image.svg`를 `kernel-figure`로 포함하고 `:alt:`에 대체 텍스트를 지정합니다. 지시문 본문은 그림 설명입니다.

`it_svg_image_example` 앵커는 생성된 그림을 다른 문장에서 참조할 수 있게 합니다. 그림 바로 앞에 고유한 참조 대상을 둡니다.

커널 그림·이미지 지시문은 Graphviz의 DOT 형식도 지원합니다. DOT 언어와 Graphviz 구문은 문서에 제시된 외부 안내서를 참고할 수 있습니다.

DOT 예제는 `../../../doc-guide/hello.dot` 파일을 포함하고 `:alt:`에 `ciao mondo`, 본문 캡션에 `Esempio DOT`를 지정합니다.

`it_hello_dot_file` 앵커는 외부 DOT 파일로 생성한 그림의 참조 대상입니다. 접근성을 위해 파일 형식과 무관하게 의미 있는 대체 텍스트를 제공해야 합니다.

외부 그림 파일의 상대 경로는 현재 문서 위치를 기준으로 계산되므로 문서나 자산을 이동할 때 함께 갱신해야 합니다. 경로 오류는 이미지 누락 또는 빌드 경고로 나타납니다.

    .. kernel-figure::  ../../../doc-guide/svg_image.svg
       :alt:    una semplice immagine SVG

       Una semplice immagine SVG

.. _it_svg_image_example:

.. kernel-figure::  ../../../doc-guide/svg_image.svg
   :alt:    una semplice immagine SVG

   Una semplice immagine SVG

Le direttive del kernel per figure ed immagini supportano il formato **DOT**,
per maggiori informazioni

* DOT: http://graphviz.org/pdf/dotguide.pdf
* Graphviz: http://www.graphviz.org/content/dot-language

Un piccolo esempio (:ref:`it_hello_dot_file`)::

  .. kernel-figure::  ../../../doc-guide/hello.dot
     :alt:    ciao mondo

     Esempio DOT

.. _it_hello_dot_file:

.. kernel-figure::  ../../../doc-guide/hello.dot
   :alt:    ciao mondo

   Esempio DOT

.. _it_sphinx_kfigure:

Figure ed immagini
==================

Se volete aggiungere un'immagine, utilizzate le direttive ``kernel-figure``
e ``kernel-image``. Per esempio, per inserire una figura di un'immagine in
formato SVG (:ref:`it_svg_image_example`)::

    .. kernel-figure::  ../../../doc-guide/svg_image.svg
       :alt:    una semplice immagine SVG

       Una semplice immagine SVG

.. _it_svg_image_example:

.. kernel-figure::  ../../../doc-guide/svg_image.svg
   :alt:    una semplice immagine SVG

   Una semplice immagine SVG

Le direttive del kernel per figure ed immagini supportano il formato **DOT**,
per maggiori informazioni

* DOT: http://graphviz.org/pdf/dotguide.pdf
* Graphviz: http://www.graphviz.org/content/dot-language

Un piccolo esempio (:ref:`it_hello_dot_file`)::

  .. kernel-figure::  ../../../doc-guide/hello.dot
     :alt:    ciao mondo

     Esempio DOT

.. _it_hello_dot_file:

.. kernel-figure::  ../../../doc-guide/hello.dot
   :alt:    ciao mondo

   Esempio DOT

kernel-render로 DOT 코드 포함

`kernel-render` 지시문은 별도 파일 대신 문서 안에 렌더링 코드를 직접 넣습니다. 예제는 렌더러 이름으로 `DOT`을 지정합니다.

`:alt:`는 대체 설명이고 `:caption:`은 표시 캡션입니다. 본문에는 `digraph foo`와 `bar`에서 `baz`로 향하는 간선을 정의한 DOT 코드를 넣습니다.

Graphviz가 설치돼 있으면 벡터 이미지로 렌더링됩니다. 설치돼 있지 않으면 같은 코드가 텍스트 블록으로 표시되어 문서 빌드를 완전히 막지 않습니다.

`it_hello_dot_render` 앵커는 인라인 DOT 렌더링 결과를 참조합니다. 외부 파일 방식과 마찬가지로 결과에 고유한 참조 이름을 줄 수 있습니다.

`kernel-render`는 일반 figure 지시문의 옵션을 모두 지원하고 `caption` 옵션을 추가합니다. 캡션 값이 있으면 figure 노드를, 없으면 image 노드를 만듭니다.

그림에 교차 참조를 추가하려면 캡션이 필요합니다. 참조 가능한 번호·설명이 있는 figure와 단순 image를 구분하는 조건입니다.

도구가 없을 때 원시 코드를 보여주는 대체 동작은 문서 정보를 완전히 잃지 않게 합니다. 그렇더라도 배포용 문서에서는 의도한 벡터 이미지가 실제 생성되는 환경으로 최종 결과를 검토해야 합니다.

  .. kernel-render:: DOT
     :alt: foobar digraph
     :caption: Codice **DOT** (Graphviz) integrato

     digraph foo {
      "bar" -> "baz";
     }

La rappresentazione dipenderà dei programmi installati. Se avete Graphviz
installato, vedrete un'immagine vettoriale. In caso contrario, il codice grezzo
verrà rappresentato come *blocco testuale* (:ref:`it_hello_dot_render`).

.. _it_hello_dot_render:

.. kernel-render:: DOT
   :alt: foobar digraph
   :caption: Codice **DOT** (Graphviz) integrato

   digraph foo {
      "bar" -> "baz";
   }

Tramite la direttiva ``kernel-render`` è possibile aggiungere codice specifico;
ad esempio nel formato **DOT** di Graphviz.::

  .. kernel-render:: DOT
     :alt: foobar digraph
     :caption: Codice **DOT** (Graphviz) integrato

     digraph foo {
      "bar" -> "baz";
     }

La rappresentazione dipenderà dei programmi installati. Se avete Graphviz
installato, vedrete un'immagine vettoriale. In caso contrario, il codice grezzo
verrà rappresentato come *blocco testuale* (:ref:`it_hello_dot_render`).

.. _it_hello_dot_render:

.. kernel-render:: DOT
   :alt: foobar digraph
   :caption: Codice **DOT** (Graphviz) integrato

   digraph foo {
      "bar" -> "baz";
   }

La direttiva *render* ha tutte le opzioni della direttiva *figure*, con
l'aggiunta dell'opzione ``caption``. Se ``caption`` ha un valore allora
un nodo *figure* viene aggiunto. Altrimenti verrà aggiunto un nodo *image*.
L'opzione ``caption`` è necessaria in caso si vogliano aggiungere dei
riferimenti (:ref:`it_hello_svg_render`).

kernel-render로 SVG 코드 포함

SVG 코드도 `.. kernel-render:: SVG` 지시문 안에 직접 작성할 수 있습니다. 렌더러 종류만 DOT에서 SVG로 바꾸고 figure 관련 옵션은 같은 방식으로 사용합니다.

예제는 `:caption: Integrare codice SVG`와 `:alt: so-nw-arrow`를 지정합니다. 캡션은 참조 가능한 figure를 만들고 대체 텍스트는 이미지 의미를 전달합니다.

본문에는 XML 선언과 `<svg>` 루트 요소를 그대로 넣습니다. 실제 예제는 너비·높이·viewBox를 정의하고 선과 다각형으로 화살표를 그립니다.

SVG 요소의 좌표, `stroke-width`, 회전 변환 같은 코드는 이미지의 실제 형상을 결정하므로 번역 과정에서 바꾸지 않습니다. 설명과 대체 텍스트만 문서 언어에 맞게 작성합니다.

`it_hello_svg_render` 앵커는 인라인 SVG 결과의 참조 대상입니다. 외부 SVG 파일과 인라인 SVG 중 유지보수와 재사용 요구에 맞는 방식을 선택합니다.

  .. kernel-render:: SVG
     :caption: Integrare codice **SVG**
     :alt: so-nw-arrow

     <?xml version="1.0" encoding="UTF-8"?>
     <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...>
        ...
     </svg>

.. _it_hello_svg_render:

.. kernel-render:: SVG
   :caption: Integrare codice **SVG**
   :alt: so-nw-arrow

   <?xml version="1.0" encoding="UTF-8"?>
   <svg xmlns="http://www.w3.org/2000/svg"
     version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
   <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
   <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
   </svg>

Per la scrittura di codice **SVG**::

  .. kernel-render:: SVG
     :caption: Integrare codice **SVG**
     :alt: so-nw-arrow

     <?xml version="1.0" encoding="UTF-8"?>
     <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...>
        ...
     </svg>

.. _it_hello_svg_render:

.. kernel-render:: SVG
   :caption: Integrare codice **SVG**
   :alt: so-nw-arrow

   <?xml version="1.0" encoding="UTF-8"?>
   <svg xmlns="http://www.w3.org/2000/svg"
     version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
   <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
   <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
   </svg>