Commit 0ae7cd87 authored by Shubham  .'s avatar Shubham .
Browse files

Create a single script to generate qthelp files, add custom styles and extract the keywords

parent 24bbf9c0
Pipeline #26112 failed with stage
in 3 minutes and 17 seconds
# 1. Creation of `qhp`
It stands for Qt Help Project. This is simiar to xml's file format. It contains the table of contents, indices, and references to the actual documentation files (*.html). This file is later passed to qhcp (Qt Help Collection File). This file contains various tags like table of contents, section tag for defining the actual documentation, keywords tag for defining the indices for the documentation, files tag for listing all the files required. [Click here for more details on qhp](https://doc.qt.io/qt-5/qthelpproject.html)
### Steps to extract the indices from `index.hhk` file to add them to `qhp`
`index.hhk` is an index file shipped with the Maxima documentation. To extract all the indices, run the python script named `index_parser.py` over the index file to get the keywords listed for `qhp` file. Copy and paste the `output.txt` file's content to `qhp` file under keywords section.
# 2. Creation of `qhcp`
It is an XML file that contains references to the compressed help files that should be included in the help collection. This file can be passed to the help generator for creating a `qhc` and `qch` files in one go. [Refer this link for more information](https://doc.qt.io/qt-5/qthelp-framework.html#qt-help-collection-project)
### Steps to generate `qhp` and `qhcp`
Copy the file named `qthelp_generator.py` and custom style sheets named `main.css` to the location where the `Maxima` HTML files exists. Then simply run the command `python qthelp_generator.py`. This script is all-in-one. It does the task of adding custom stylesheets defined in `main.css`, extracting the keywords from `index.hhk` and generation of QtHelp files named `qhp` and `qhcp`.
NOTE: store the `index.hhk`, `main.css` in the same folder as that of the `Maxima` documentation and the script should be placed there as well.
### Creation of `qhc` and `qch`
Use the following command to generate the above said files.
qhelpgenerator doc.qhp -o doc.qch
qhelpgenerator help.qhcp -o help.qhc
# 3. Steps for adding custom style to the Maxima documentation
Add your custom styles to `main.css`. To apply custom them, place the python script named `css_injector.py` in the same location as that of all the Maxima's documentation's HTML files. Then run the script. It will inject code into HTML files to link them to `main.css` file.
### Steps for adding custom style to the Maxima documentation
Add your custom styles to `main.css`. To apply custom them, place the python script named `qthelp_generator.py` in the same location as that of all the Maxima's documentation's HTML files. Then run the script. It will inject code into HTML files to link them to `main.css` file.
import os
files = os.listdir('.')
for fi in files:
if fi.endswith('.html'):
# open file and reach to the 62 line
fp = open(fi, 'r')
lines_list = fp.readlines()
lines_list.insert(61, '<link rel="stylesheet" type="text/css" href="./main.css">')
fp.close()
# link the css file
fp = open(fi, 'w')
fp.writelines(lines_list)
fp.close()
# script to parse index.hhk and generate .xml file
fp = open('./index.hhk', 'r')
fp2 = open('./output.txt', 'w')
for li in fp:
if li.startswith('<li>'):
line2 = fp.next()
line3 = fp.next()
if not line2:
break
else:
ln2_lastindex = line2.rindex('"')
ln3_lastindex = line3.rindex('"')
name = line3[29:ln3_lastindex]
ref = line2[30:ln2_lastindex]
fp2.write('<keyword name = "{}" ref = "{}"/>\n'.format(name, ref))
fp.close()
fp2.close()
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor,
# Boston, MA 02110-1301, USA.
# ---
# Copyright (C) 2020 Shubham <aryan100jangid@gmail.com>
#
# script to parse index.hhk and generate a txt file containing all the keywords
# and then genearte QtHelp files using the keywords generated
# This script also adds custom styles to the html pages
import os
from bs4 import BeautifulSoup
#######################################
#code for adding custom styles to html#
######################################
files = os.listdir('.')
for fi in files:
if fi.endswith('.html'):
# open file and reach to the 62 line
fp = open(fi, 'r')
lines_list = fp.readlines()
lines_list.insert(61, '<link rel="stylesheet" type="text/css" href="./main.css">')
fp.close()
# link the css file
fp = open(fi, 'w')
fp.writelines(lines_list)
fp.close()
index = open('./index.hhk', 'r')
# QtHelp files
qhp = open('./help.qhp', 'w')
qhcp = open('./help.qhcp', 'w')
#######################################
#code for generation of QtHelp files##
######################################
# populate qhp file with headers and table of contents
qhp.writelines("""<?xml version="1.0" encoding="UTF-8"?>
<QtHelpProject version="1.0">
<namespace>org.kde.maxima</namespace>
<virtualFolder>doc</virtualFolder>
<customFilter name="Maxima">
<filterAttribute>Maxima Documentation</filterAttribute>
<filterAttribute>5.42</filterAttribute>
</customFilter>
<filterSection>
<toc>
<section title="Maxima 5.42 Documentation" ref="maxima.html">
<section title="Maxima Infrastructure" ref="maxima.html#SEC1">
<section title="Introduction to Maxima" ref="maxima_1.html"></section>
<section title="Bug Detection and Reporting" ref="maxima_2.html"></section>
<section title="Help" ref="maxima_3.html"></section>
<section title="Command Line" ref="maxima_4.html"></section>
<section title="Data Types and Structures" ref="maxima_5.html"></section>
<section title="Expressions" ref="maxima_6.html"></section>
<section title="Operators" ref="maxima_7.html"></section>
<section title="Evaluation" ref="maxima_8.html"></section>
<section title="Simplification" ref="maxima_9.html"></section>
<section title="Mathematical Functions" ref="maxima_10.html"></section>
<section title="Maximas Database" ref="maxima_11.html"></section>
<section title="Plotting" ref="maxima_12.html"></section>
<section title="File Input and Output" ref="maxima_13.html"></section>
</section>
<section title="Support for specific areas of mathematics" ref="maxima.html#SEC2">
<section title="Polynomials" ref="maxima_14.html"></section>
<section title="Special Functions" ref="maxima_15.html"></section>
<section title="Elliptic Functions" ref="maxima_16.html"></section>
<section title="Limits" ref="maxima_17.html"></section>
<section title="Differentiation" ref="maxima_18.html"></section>
<section title="Integration" ref="maxima_19.html"></section>
<section title="Equations" ref="maxima_20.html"></section>
<section title="Differential Equations" ref="maxima_21.html"></section>
<section title="Numerical" ref="maxima_22.html"></section>
<section title="Matrices and Linear Algebra" ref="maxima_23.html"></section>
<section title="Affine" ref="maxima_24.html"></section>
<section title="itensor" ref="maxima_25.html"></section>
<section title="ctensor" ref="maxima_26.html"></section>
<section title="atensor" ref="maxima_27.html"></section>
<section title="Sums, Products and Series" ref="maxima_28.html"></section>
<section title="Number Theory" ref="maxima_29.html"></section>
<section title="Symmetrics" ref="maxima_30.html"></section>
<section title="Groups" ref="maxima_31.html"></section>
</section>
<section title="Advanced facilities and programming" ref="maxima.html#SEC3">
<section title="Runtime Environment" ref="maxima_32.html"></section>
<section title="Miscellaneous Options" ref="maxima_33.html"></section>
<section title="Rules and Patterns" ref="maxima_34.html"></section>
<section title="Sets" ref="maxima_35.html"></section>
<section title="Function Definition" ref="maxima_36.html"></section>
<section title="Program Flow" ref="maxima_37.html"></section>
<section title="Debugging" ref="maxima_38.html"></section>
</section>
<section title="Additional packages" ref="maxima.html#SEC4">
<section title="alt-display" ref="maxima_39.html"></section>
<section title="asympa" ref="maxima_40.html"></section>
<section title="augmented_lagrangian" ref="maxima_41.html"></section>
<section title="Bernstein" ref="maxima_42.html"></section>
<section title="bitwise" ref="maxima_43.html"></section>
<section title="bode" ref="maxima_44.html"></section>
<section title="celine" ref="maxima_45.html"></section>
<section title="clebsch_gordan" ref="maxima_46.html"></section>
<section title="cobyla" ref="maxima_47.html"></section>
<section title="combinatorics" ref="maxima_48.html"></section>
<section title="contrib_ode" ref="maxima_49.html"></section>
<section title="desciptive" ref="maxima_50.html"></section>
<section title="diag" ref="maxima_51.html"></section>
<section title="distrib" ref="maxima_52.html"></section>
<section title="draw" ref="maxima_53.html"></section>
<section title="drawdf" ref="maxima_54.html"></section>
<section title="dynamics" ref="maxima_55.html"></section>
<section title="engineering-format" ref="maxima_56.html"></section>
<section title="ezunits" ref="maxima_57.html"></section>
<section title="f90" ref="maxima_58.html"></section>
<section title="finance" ref="maxima_59.html"></section>
<section title="fractals" ref="maxima_60.html"></section>
<section title="ggf" ref="maxima_61.html"></section>
<section title="graphs" ref="maxima_62.html"></section>
<section title="grobner" ref="maxima_63.html"></section>
<section title="impdiff" ref="maxima_64.html"></section>
<section title="interpol" ref="maxima_65.html"></section>
<section title="lapack" ref="maxima_66.html"></section>
<section title="lbfgs" ref="maxima_67.html"></section>
<section title="lindstedt" ref="maxima_68.html"></section>
<section title="linearalgebra" ref="maxima_69.html"></section>
<section title="lsquares" ref="maxima_70.html"></section>
<section title="makeOrders" ref="maxima_71.html"></section>
<section title="minpack" ref="maxima_72.html"></section>
<section title="mnewton" ref="maxima_73.html"></section>
<section title="numericalio" ref="maxima_74.html"></section>
<section title="operatingsystem" ref="maxima_75.html"></section>
<section title="opsubst" ref="maxima_76.html"></section>
<section title="orthopoly" ref="maxima_77.html"></section>
<section title="ratpow" ref="maxima_78.html"></section>
<section title="romberg" ref="maxima_79.html"></section>
<section title="simplex" ref="maxima_80.html"></section>
<section title="simplification" ref="maxima_81.html"></section>
<section title="solve_rec" ref="maxima_82.html"></section>
<section title="stats" ref="maxima_83.html"></section>
<section title="stirling" ref="maxima_84.html"></section>
<section title="stringproc" ref="maxima_85.html"></section>
<section title="to_poly_solve" ref="maxima_86.html"></section>
<section title="unit" ref="maxima_87.html"></section>
<section title="wrstcse" ref="maxima_88.html"></section>
<section title="zeilberger" ref="maxima_89.html"></section>
</section>
<section title="Understanding maxima's output" ref="maxima.html#SEC5">
<section title="Error and Warning Messages" ref="maxima_90.html"></section>
</section>
</section>
</toc>\n
<keywords>""")
# populate qhcp file
qhcp.writelines("""<?xml version="1.0" encoding="utf-8" ?>
<QHelpCollectionProject version="1.0">
<docFiles>
<generate>
<file>
<input>help.qhp</input>
<output>help.qch</output>
</file>
</generate>
<register>
<file>help.qch</file>
</register>
</docFiles>
</QHelpCollectionProject>""")
# this way to does not work, because somehowbeautifulsoupl is unable to escape &gt and &gt;< special symbols
# html = index.read()
# soup = BeautifulSoup(html, features='html.parser')
# for i in soup.find_all('object'):
# attributes = i.findChildren()
# link = attributes[0]['value']
# keyword = attributes[1]['value']
# repr(keyword)
# if link != 'maxima_7.html#IDX227' and link != 'maxima_7.html#IDX227':
# qhp.write('<keyword name = "{}" ref = "{}"/>\n'.format(keyword, link))
# read all the keywords from index.hhk and write them to qhp under <keywords> section
for li in index:
if li.startswith('<li>'):
line2 = index.next()
line3 = index.next()
if not line2:
break
else:
ln2_lastindex = line2.rindex('"')
ln3_lastindex = line3.rindex('"')
name = line3[29:ln3_lastindex]
ref = line2[30:ln2_lastindex]
qhp.write('<keyword name = "{}" ref = "{}"/>\n'.format(name, ref))
# write the tail
qhp.writelines("""</keywords>
<files>
<file>*.html</file>
<file>figures/*.gif</file>
<file>figures/*.png</file>
<file>main.css</file>
</files>
</filterSection>
</QtHelpProject> """)
index.close()
qhp.close()
qhcp.close()
......@@ -85,12 +85,16 @@ DocumentationPanelWidget::DocumentationPanelWidget(Cantor::Session* session, QWi
QByteArray contents;
if(m_backend == QLatin1String("Maxima"))
contents = m_engine->fileData(QUrl(QLatin1String("qthelp://org.kde.cantor/doc/maxima.html#SEC_Top")));
{
contents = m_engine->fileData(QUrl(QLatin1String("qthelp://org.kde.cantor/doc/maxima.html#SEC_Top")));
}
else if(m_backend == QLatin1String("Octave"))
contents = m_engine->fileData(QUrl(QLatin1String("qthelp://org.octave.interpreter-1.0/doc/octave.html/index.html")));
{
contents = m_engine->fileData(QUrl(QLatin1String("qthelp://org.octave.interpreter-1.0/doc/octave.html/index.html")));
}
m_textBrowser->setContent(contents, QLatin1String("text/html;charset=UTF-8"));
m_textBrowser->hide();
m_textBrowser->setContent(contents, QLatin1String("text/html;charset=UTF-8"), QUrl(QLatin1String("qthelp://org.kde.cantor/doc/")));
m_textBrowser->show();
m_splitter = new QSplitter(Qt::Horizontal, this);
m_splitter->addWidget(m_tabWidget);
......@@ -99,6 +103,7 @@ DocumentationPanelWidget::DocumentationPanelWidget(Cantor::Session* session, QWi
QHBoxLayout* layout = new QHBoxLayout(this);
layout->addWidget(m_splitter);
//TODO QHelpIndexWidget::linkActivated is obsolete, use QHelpIndexWidget::documentActivated instead
connect(m_engine->contentWidget(), &QHelpContentWidget::linkActivated, this, &DocumentationPanelWidget::displayHelp);
connect(m_engine->indexWidget(), &QHelpIndexWidget::linkActivated, this, &DocumentationPanelWidget::displayHelp);
//connect(search, SIGNAL(clicked(bool)), this, SLOT(doSearch(QString)));
......@@ -145,6 +150,7 @@ void DocumentationPanelWidget::loadDocumentation()
{
const QString backend = backendName();
const QString fileName = QStandardPaths::locate(QStandardPaths::AppDataLocation, QLatin1String("documentation/") + backend + QLatin1String("/help.qch"));
m_engine->registerDocumentation(fileName);
}
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment