Metadata-Version: 2.1
Name: yangdoc
Version: 0.6.0
Summary: A project for generating YANG tree views.
Author: Joachim Wiberg
License: MIT License
        
        Copyright (c) 2024  Joachim Wiberg <troglobit@gmail.com>
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: homepage, https://github.com/troglobit/yangdoc
Project-URL: repository, https://github.com/troglobit/yangdoc
Keywords: YANG,tree,libyang,HTML,jstree
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cffi==1.16.0
Requires-Dist: libyang==2.7.1
Requires-Dist: pycparser==2.22

YANG Documentation Viewer
=========================

Very limited YANG Documentation generator based on libyang, with similar
output to that of `pyang -f jstree`.  The default output is a standalone
HTML file, called `yangdoc.html`, that can be included in documentation
bundles.


Usage
-----

See below [setup instructions](#setup) first.

```
~/src/yangdoc(main)$ python main.py -p yang -m ietf-system -e authentication -e local-users -e ntp -e ntp-udp-port -e timezone-name -m ietf-interfaces -e if-mib
INFO: Parsing ietf-system, enabling features: ['authentication', 'local-users', 'ntp', 'ntp-udp-port', 'timezone-name']
WARNING: Warning: failed to parse module: Data model "ietf-netconf-acm" not found in local searchdirs.: Loading "ietf-netconf-acm" module failed.: Parsing module "ietf-system" failed.
INFO: Parsing ietf-interfaces, enabling features: ['if-mib']
INFO: Processing module ietf-interfaces
INFO: HTML file generated: yangdoc.html
x-www-browser yang_tree_view.html
~/src/yangdoc(main)$ x-www-browser yang_tree_view.html
```


Screenshot
----------

![](screenshot.png)


Setup
-----

> These instructions have been tested on Linux Mint 21.3, but
> are mostly the same for other operating systems.

Clone the repository to your home directory:

```
~$ cd src/
~/src$ git clone https://github.com/troglobit/yangdoc
~/src$ cd yangdoc
~/src/yangdoc(main)$
```

Set up your virtual environment, this ensures all python packages
installed from `requirements.txt` are installed only in `.venv/`:

```
~/src/yangdoc(main)$ python -m venv .venv
~/src/yangdoc(main)$ source .venv/bin/activate
```

Install all required packages:

```
~/src/yangdoc(main)$ sudo apt install libyang2
~/src/yangdoc(main)$ pip install -r requirements.txt
```


Developer Notes
---------------

Use `pip-compile` from pip-tools to [manage Python requirements][4],
this makes life a lot easier since we only need pyproject.toml for all
our packaging needs.

To install locally, or just build, verifying pyproject.toml:

```
~/src/yangdoc(main)$ pip install -e .
~/src/yangdoc(main)$ python -m build
```

For uploading to PyPi, remember to install twine:

```
~/src/yangdoc(main)$ pip install twine
```

Then build and test upload:

```
~/src/yangdoc(main)$ python -m build
~/src/yangdoc(main)$ twine upload --repository-url https://test.pypi.org/legacy/ dist/*
```

Verify upload and then upload to PyPi proper:

```
~/src/yangdoc(main)$ twine upload dist/*
```


[1]: https://massimilianobruni-92986.medium.com/fix-your-python-requirements-with-pip-tools-856765d8c061
