Developer documentation¶
Core code¶
- __init__.py - CodeChat Package
- SourceClassifier.py - a module to lex source code
- CodeToRest.py - a module to translate source code to reST
- CodeToMarkdown.py - a module to translate source code to Markdown
- CodeToPretext.py - a module to translate source code to PreTeXt
- RestToCode.py - a module to translate reST to source code
- CodeToRestSphinx.py - a Sphinx extension to translate source code to reST
- mdbook_CodeChat.py - A CodeChat preprocessor for mdbook
- CommentDelimiterInfo.py - Info on comment delimiters for many languages
- __init__.py - CodeChat CSS data files
- .gitignore - Files for Git to ignore
- .flake8 - Flake8 configuration
- pyproject.toml - Configuration for black and pytest
Style sheets¶
This section presents the style sheets used for CodeChat webpages.
Testing¶
To run the tests, execute pytest test
from the root directory of the project.
- CodeToMarkdown_test.py - Unit testing
- CodeToPretext_test.py - Unit tests for PreTeXt
- CodeToRestSphinx_test.py - Unit testing for
../CodeChat/CodeToRestSphinx.py
- CodeToRest_test.py - Unit testing
- HtmlToCode_test.py - Unit testing
- RestToCode_test.py - Unit testing
- .travis.yml - Travis CI configuration
- appveyor.yml - Appveyor CI configuration
- style_test.py - Styling tests for CodeChat
Documentation generation¶
To build the documentation, execute sphinx-build -d _build/doctrees . _build
from the root directory of the project.
Packaging¶
Ideas / todo items¶
Implement caching and correct styling for mdbook_CodeChat.py - A CodeChat preprocessor for mdbook.
Introduce a new directive such as
code-ref
that allows referencing names in the code. Use ctags to generate these references.Perhaps
:code-ref:`optional-source-file.ext::scope-0::scope-1::...::scope-n <optional name>`
.Provide an output-independent function to run ctags on a list of source files, then read the tags into a data structure:
Dict[ # A relative path to the source file. str, # A dict of names in this source file. Dict[ # Include both all names in the top-level scope plus any # non-conflicting name in a lower scope. That is, given a # variable named ``foo::bar``, this dict would contain both # ``foo`` as the top-level scope and ``bar``, unless there # was another variable named ``zot::bar`` in the same file # (meaning that ``bar`` isn't a unique name). str, # Information about this name: Tuple[ # The line number where this name was defined. int, # If this name defines a scope containing more names, # this contains them, again as a ``Dict[int, Optional # [Dict]]``. Optional[Dict]]]]
Provide per-output ways to embed this in the output.
Profile this to see what’s slow.