Metadata-Version: 2.1
Name: sphinxcontrib.kana-text
Version: 0.30.0
Summary: KanaText class extends the functionality of Text class, for someone who use index/glossary directives.
Home-page: https://qiita.com/tags/sphinxcotrib.kana_text
Author: @koKekkoh
Maintainer: KaKkouo
License: BSD 2-Clause License
Download-URL: https://pypi.org/project/sphinxcontrib.kana-text/
Project-URL: Knowledge, https://qiita.com/tags/sphinxcotrib.kana_text
Project-URL: Code, https://github.com/KaKkouo/kana_text
Project-URL: Issue tracker, https://github.com/KaKkouo/kana_text/issues
Keywords: sphinx,sphinxcontrib,japanese,ja,kana_text,glossary,index,kana
Platform: any
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: Japanese
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Documentation :: Sphinx
Classifier: Topic :: Utilities
Description-Content-Type: text/x-rst
License-File: LICENSE

.. image:: https://readthedocs.org/projects/kana_text/badge/?version=latest
   :target: https://kana_text.readthedocs.io/en/latest/
   :alt: Documentation Status

.. image:: https://circleci.com/gh/KaKkouo/kana_text.svg?style=shield
   :target: https://circleci.com/gh/KaKkouo/kana_text
   :alt: Build Status (CircleCI)

.. image:: https://codecov.io/gh/KaKkouo/kana_text/branch/main/graph/badge.svg
   :target: https://codecov.io/gh/KaKkouo/kana_text
   :alt: Code Coverage Status (Codecov)

.. image:: https://img.shields.io/badge/License-BSD%202--Clause-blue.svg
   :target: https://opensource.org/licenses/BSD-2-Clause
   :alt: BSD 2 Clause

This is a sphinx extention. It extends the functionality of the Text class. Any person, who uses index/glossary directives with Japanse Kanji, is to be so happy.

.. image:: https://i.gyazo.com/4cbf3408c162fb2bfcc493661d35a42b.png

If word_list.txt is used by kana_text_word_file parameter, the genindex.html is created without editing rst files.

QUICK START
-----------

installtion

.. code-block:: sh

   $ pip install sphindexer sphinxcontrib.kana_text

conf.py:

.. code-block:: python

   extensions = ['sphinxcontrib.kana_text']

.. code-block:: python

   #kana_text_word_file = '~/.config/sphinx/word_list.txt'
   #kana_text_word_list = ['ようご|用語^21', 'ぶんしょさくせい|文書作成^2222',]
   #kana_text_indexer_mode = 'small'
   #kana_text_on_genindex = False

.. warning::

   - 'word_list.txt' is required for kana_text_word_file
   - 'genindex.html' is required for kana_text_on_genindex = True.
   - both parameters are valid only against genindex.html.

rst file:

.. code-block:: rst

   .. index:: ようご|用語^21

.. code-block:: rst

   .. glossary::

      ようごいち|用語壱^212
        用語１の説明。

.. code-block:: rst

   夜空に浮かぶ\ :index:`あまた|数多^21`\ の星々が\ :kana:`きらめいて|煌めいて^2c`\ いる。

.. image:: https://i.gyazo.com/63fe4ccfaa8a57bb2d8db50c0a689cad.png

.. code-block:: rst

   :term:`linkt to the term<ようごいち|用語壱^212>`

build:

.. code-block:: sh

   $ make html

genindex.html
-------------

.. code-block:: sh

   $ sphinx-kana-genindex
   $ mv genindex.html.sample path_to_sphinx_project/_templates/genindex.html

note
----
The indexer function of this package is handled by "sphindexer".
This package also serves as a reference implementation of how to add reading information.

If you want to use your own notation for reading, please refer to the implementation on Github and create your own notation. 
The analysis of your own notation will be integrated into "KanaText".

DEVELOPMENT
-----------
structure of the data for genindex.html

- entry: {file_name: [(entry_type, value, target, main, index_key)]}

    - file_name: the name without suffix
    - entries: [entry]

        - entry: (entry_type, value, target, main, index_key)

            - entry_type: in('single', 'pair', 'triple', 'see', 'seealso')
            - value: 'word', 'word; word' or 'word; word; word'
            - target: the target id
            - main: 'main' or ''
            - index_key: classifier or None

- unit(the other entry): [(classifier, term, subterm, emphasis, file_name, target, index_key)]

    - classifier: KanaText(index_key, word[:1] or a letter made by word[:1])
    - term: KanaText(word)
    - subterm: '', KanaText(word), KanaText(word1) and KanaText(word2)
    - emphasis
    - file_name
    - target
    - index_key

- genidex: [(classifier, terms)]

    - classifier: KanaText
    - terms: [(term, list)]

        - term: KanaText
        - list: [links, subterms, index_key]

            - links: [(main, uri)]
            - subterms: [(subterm, links)]

                - subterm: SubTerm[KanaText]
                - links: [(main, uri)]

            - index_key: str

variables

- term: KanaText OBJect. it had better to be 'ktobj' vaiable name.
- rawword: ex. 'かな|言葉^11'
- rawtext: ex. 'かな|言葉^11', 'かな|言葉^11; いい|壱壱^11' or 'かな|言葉^11; ...; ...'
- rawsouce: means Element.rawsource.
- text: the string 'かな|言葉' of 'かな|言葉^11', by object.astext() of KanaText.
- word: use as hier.
- hier: the string '言葉' of 'かな|言葉^11', by object.ashier() which means hieroglyph.
- kana: the string 'かな' of 'かな|言葉^11'. by object.askana()
- ruby: ex. [(True, ('田', 'た')), (True, ('中', 'なか'))]
- html: ex. '<ruby><rb>言葉</by><rp></rp><rt>かな</rt><rp></rp></ruby>'
- latex: (T.B.D.)
- epub: (T.B.D.)
- separator: used by re.split()
- delimiter: used by object.astext(), etc.
- option_marker: the '^' of 'かな|言葉^11'

methods

- ashier: return a string like hieroglyph
- astext: return a string like a eacy identifier
- askana: return a string which is reading
- asruby: return a list data for the display with ruby. for genindex.html.
- ashtml: return a string which is made with html tags. for genindex.html and glossary.
- __eq__: return self.astext() == other,  to be identified easily for unittest
- __str__: return a string by ashier/ashtml for jinja2

KanaText(ex. 'かな|言葉^11')

- object[0]: '言葉’
- object[1]: 'かな'
- object['delimiter']: '|'
- object['ruby']: 'specific'
- object['option']: '11'
- object.whatiam: in('classifier', 'term':default, 'subterm')
- object.__eq__: used by unittest and IndexRack.generate_genindex_data
- object.__str__: used by jinja2. use object.whatiam

ExIndexEntry(ex. 'ああ|壱壱^11; いい|弐弐^11; うう|参参^11')

- object[0]: KanaText('ああ|壱壱^11')
- object[1]: KanaText('いい|弐弐^11')
- object[2]: KanaText('うう|参参^11')
- object['entry_type']: 'single', 'pair', 'triple', 'see' or 'seealso'
- object['file_name']: file name
- object['target']: target id
- object['main']: 'main' or ''
- object['index_key']: None or classifier
- object.make_IndexUnit(): return [IndexUnit, IndexUnit, ...]

ExIndexRack

- object[n]: IndexUnit(...)
- object.append(): make/update classifier_catalog and kana_katalog
- object.extend(): call the object.append() by each IndexUnit object
- object.udpate(): update IndexUnit object with classifier_catalog and kana_catalog
- object.sort(): to be sorted
- object.generate_genindex_data()

ExIndexUnit

- object._sortkey: for emphasis which means 'main'.
- object[0]: KanaText(classifier)
- object[1]: KanaText(main term)
- object[2]: SubTerm([], [KanaText(2nd)], or [KanaText(2nd), KanaText(3rd)])
- object[3]: emphasis code ('main': 3, '': 5, 'see': 8, 'seealso': 9)
- object['file_name']: target file
- object['target']: target id
- object['main']: emphasis
- object['index_key']: None or classifier
- object.delimiter: ' ' or ', '
- object.get_children: [object[1], object[2][0], object[2][1]]

ExSubTerm

- object[0]: KanaText
- object[1]: KanaText
- object._delimiter


