detche / helpgen (public) (License: GPLv3) (since 2017-10-19) (hash sha1)
Help document project processor
Clone URLs: https://rocketgit.com/user/detche/helpgen ssh://rocketgit@ssh.rocketgit.com/user/detche/helpgen git://git.rocketgit.com/user/detche/helpgen
master
List of commits:
Subject Hash Author Date (UTC)
Initial commit 14d016d7ec773a17c3d72fc8352f6c683825e040 Detche 2017-10-19 20:44:14
Commit 14d016d7ec773a17c3d72fc8352f6c683825e040 - Initial commit
Author: Detche
Author date (UTC): 2017-10-19 20:44
Committer name: Detche
Committer date (UTC): 2017-10-19 20:44
Parent(s):
Signing key:
Tree: de322ee20c68e0967f0dc97599f22f6c380af021
File Lines added Lines deleted
.gitignore 1 0
helpgen/__init__.py 0 0
helpgen/__main__.py 65 0
helpgen/category.py 37 0
helpgen/document.py 4 0
helpgen/item.py 100 0
helpgen/project.py 0 0
requirements.txt 1 0
setup.py 20 0
File .gitignore added (mode: 100644) (index 0000000..c18dd8d)
1 __pycache__/
File helpgen/__init__.py added (mode: 100644) (index 0000000..e69de29)
File helpgen/__main__.py added (mode: 100644) (index 0000000..5733094)
1 #!/usr/bin/env python
2
3 import argparse
4
5
6
7 def entry():
8 parser = argparse.ArgumentParser(
9 prog='helpgen',
10 description='Utility that works on building user help documents.')
11
12 parser.add_argument('--verbose', '-v', action='count', help='print verbose')
13 parser.add_argument('--version', action='version', version="%(prog)s 1.0")
14
15 subparsers = parser.add_subparsers(dest="command")
16
17 # BUILD command parser
18
19 targets=["web", "pdf", "chm"]
20
21 parser_build = subparsers.add_parser(
22 'build',
23 help='builds the given source',
24 description='Building transforms the source into the given document type.')
25
26 parser_build.add_argument(
27 'src',
28 help='Folder that contains project to build.',
29 type=str)
30
31 parser_build.add_argument(
32 'dst',
33 nargs='?',
34 help='Folder to place the built document into.',
35 default='./build',
36 type=str)
37
38 parser_build.add_argument(
39 '--target',
40 '-t',
41 help='Type of output that should be generated.',
42 default='web',
43 choices=targets,
44 type=str)
45
46 parser_build.add_argument(
47 '--edition',
48 '-e',
49 help='Edition of the document to make. Can be specified several times.',
50 action='append',
51 type=str)
52
53 # NEW command parser
54
55 parser_new = subparsers.add_parser(
56 'new',
57 help='creates a new project squeleton',
58 description='Allows to create a new project squeleton at given path.')
59
60
61 args = parser.parse_args()
62
63 if args.command is not None:
64 print("will do: " + args.command)
65 # do what is asked
File helpgen/category.py added (mode: 100644) (index 0000000..3046570)
1 #!/usr/bin/env python
2 """ A category corresponds to a Item with no content, simply children. """
3
4 import os
5 import sys
6
7 from item import Item
8
9 class Category(Item):
10 def __init__(self, path=None):
11 if path is not None:
12 if not os.path.exists(path):
13 raise FileNotFoundError('category path not found.', path)
14 assert os.path.isdir(path), 'non-dir given to Category constructor.'
15
16 # Open our metadata file. It should be named category.yaml/yml
17 metapath = os.path.join(path, 'category.yml')
18 if not os.path.exists(metapath):
19 metapath = os.path.join(path, 'category.yaml')
20 if not os.path.exists(metapath):
21 raise FileNotFoundError('Category metadata file not found.',
22 metapath)
23 super(Category, self).__init__(metapath)
24
25 def can_have_children(self):
26 """ Category children are expected to be Categories or Documents. """
27 return True
28
29 if __name__ == '__main__':
30 args = sys.argv[1:]
31 if len(args) == 0:
32 print("expected directory path")
33 exit()
34
35 cat = Category(args[0])
36 print(cat.name())
37
File helpgen/document.py added (mode: 100644) (index 0000000..7ad69c7)
1 #!/usr/bin/env python
2 """ Represents a document part that can be included in the final document."""
3
4
File helpgen/item.py added (mode: 100644) (index 0000000..6d4b4da)
1 #!/usr/bin/env python
2 """ An item can be included in a Table of Content.
3
4 It is located in a folder and usually have a YAML document that describe what
5 it is and what it contains. """
6
7 import sys
8 import os
9 import yaml
10
11 class Item:
12 def __init__(self, path=None):
13 """ Initializes the Item by parsing the Yaml file, if provided."""
14 self.path = ''
15 self.metadata = None
16 self.parent = None
17 self.children = []
18
19 if path is not None:
20 assert len(path), 'Empty path given to Item constructor.'
21 if not os.path.exists(path):
22 raise FileNotFoundError('path to meta document is invalid.',
23 path)
24 with open(path) as f:
25 self.metadata = yaml.safe_load(f)
26 self.path = path
27
28 def can_have_children(self):
29 """ Whether or not this item can have children. """
30 return False
31
32 def _get_value(self, name, lang=''):
33 """ Get the value designated by name or its translation.
34
35 if given lang is not found, the untranslated value is returned."""
36 if self.metadata is None:
37 return ''
38 assert len(name), 'Given empty name to get_value function.'
39 if len(lang) and 'translations' in self.metadata:
40 for translation in self.metadata['translations']:
41 assert 'lang' in translation, 'Translation misses lang value.'
42 if translation['lang'] == lang:
43 if name in translation:
44 return translation[name]
45 if name in self.metadata:
46 return self.metadata[name]
47 return ''
48
49 def _get_list(self, name, lang='', substitute=True):
50 """ Get the list designated by name or its translation.
51
52 If the substitute argument is set to False, the returned list will
53 be a concatenation of the untranslated values and the translated
54 ones. If substitute is True, only the values of the translated list
55 will be returned.
56 """
57 if self.metadata is None:
58 return ''
59 assert len(name), 'Given empty name to get_array function.'
60 array=[]
61 if len(lang) and 'translations' in self.metadata:
62 for translation in self.metadata['translations']:
63 assert 'lang' in translation, 'Translation misses lang value.'
64 if translation['lang'] == lang:
65 if name in translation:
66 array = translation[name]
67 if substitute:
68 return array
69 if name in self.metadata:
70 array += self.metadata[name]
71 return array
72
73 def is_included_in(self, editions):
74 """ Whether the item should be included in the given edition(s). """
75 if self.metadata is None return False
76 if 'editions' not in self.metadata return True
77 if isinstance(editions, str):
78 if editions in self.metadata.editions return True
79 return False
80 if isinstance(editions, list):
81 for edition in editions:
82 if edition in self.metadata.editions return True
83 return False
84
85 def set_parent(self, parent):
86 """ Set the parent of this Item. Called by add_child(). """
87 assert isinstance(parent, Item), 'cannot set non-Item as parent.'
88 self.parent = parent
89
90 def add_child(self, child):
91 """ Add a child to this Item. """
92 assert isinstance(child, Item), 'cannot set non-Item as child.'
93 assert self.can_have_children(), 'item cannot have children.'
94 children += child
95 child.set_parent(self)
96
97 def name(self, lang=''):
98 """ Name of the item. Return translated value if lang is given. """
99 return self._get_value('name', lang=lang)
100
File helpgen/project.py added (mode: 100644) (index 0000000..e69de29)
File requirements.txt added (mode: 100644) (index 0000000..84041f8)
1 PyYAML>=3.0
File setup.py added (mode: 100644) (index 0000000..e1639b6)
1 from setuptools import setup
2
3 setup(
4 name='helpgen',
5 version='1.0',
6 url='https://www.github.com/detche/helpgen',
7 license='MIT',
8 description='Help document generator.',
9 author='Guillaume Detcheverry',
10 author_email='gdetcheverry@gmail.com',
11 packages=["helpgen"],
12 include_package_data=True,
13 install_requires=[],
14 entry_points={
15 'console_scripts': [
16 'helpgen = helpgen.__main__:entry',
17 ]
18 },
19 zip_safe=False
20 )
Hints:
Before first commit, do not forget to setup your git environment:
git config --global user.name "your_name_here"
git config --global user.email "your@email_here"

Clone this repository using HTTP(S):
git clone https://rocketgit.com/user/detche/helpgen

Clone this repository using ssh (do not forget to upload a key first):
git clone ssh://rocketgit@ssh.rocketgit.com/user/detche/helpgen

Clone this repository using git:
git clone git://git.rocketgit.com/user/detche/helpgen

You are allowed to anonymously push to this repository.
This means that your pushed commits will automatically be transformed into a merge request:
... clone the repository ...
... make some changes and some commits ...
git push origin main