Feature Request: Documentation and Instructions For How To Build The Website From The Python Scripts
jgarte opened this issue · 2 comments
Hi
This is a feature request for Documentation and Instructions For How To Build The Website From The Python Scripts. and other files. There is no Makefile so I'm not sure which one is the entry point script and what they are for. I think it should be documented for the community users and contributors.
There were initially two directories html_in and html_out. The former, I believe, was the output from converting the specification .texi files to HTML using texi2any. The latter contained the final (live) HTML pages, which were processed by convert.py. Now the html_out directory has been renamed to pages, and contributors are expected to edit these HTML files directly. The convert.py script is no longer needed.
You should run backlinks.py after adding or deleting any hyperlinks. This will ensure that the linked page(s) display the correct backlinks.
You shouldn't need to touch glossary_links.py. That was used to convert italicized text throughout the specification into hyperlinks to the relevant glossary entries. If you are adding content to the specification (like a usage example), and you reference a term in the glossary, this should be manually hyperlinked. Each term in the glossary has a corresponding HTML ID, and these are listed in glossary-terms.txt.
Not sure about tables.py. I assume it was used to process the output from texi2any, and don't believe it's needed anymore.
@fonol, is there anything you would like to add/correct about my explanation?
There is some relevant discussion here: #21