search

grimme-lab / xtb_docs

https://xtb-docs.readthedocs.io/en/latest/
Creative Commons Attribution Share Alike 4.0 International
35 stars 35 forks source link

Link xcontrol documentation to website #22

Closed tobigithub closed 4 years ago

tobigithub commented 4 years ago

This took me a long time to figure out and confused me very much, lots of pages mention "xcontrol(7)" but when searching the online web docs nothing shows up. So it would be nice to link to the man page or add the xcontrol parameter page to the website, because otherwise its not searchable via the little search box.

Example search for enan, should link to xcontrol, but yields nothing: https://xtb-docs.readthedocs.io/en/latest/search.html?q=enan&check_keywords=yes&area=default

The page https://xtb-docs.readthedocs.io/en/latest/xcontrol.html# should link to here: https://github.com/grimme-lab/xtb/blob/master/man/man7/xcontrol.7.txt

awvwgk commented 4 years ago

We started documenting xtb and its features in asciidoc and exporting them to roff (have a look at man man). If you install xtb properly you can always access the man pages with man xtb and man xcontrol.

Now with the read-the-docs page we would have to port everything to restructuredtext again.

awvwgk commented 4 years ago

After looking into restructuredtext for man pages and sphinx with asciidoc, there seems to be not much room for intercompatible solutions.

Also, after letting several people re-read https://xtb-docs.readthedocs.io/en/latest/setup.html, we found all additional information to be only one search or shell command away, which is fine in my opinion.

tobigithub commented 4 years ago

@awvwgk I only report from the user base, I think the documentation is excellent and will enable many users in the future to use xtb. Having all the data on readthedocs.io and as PDF is great!

But for me as a user, if there are features that are hidden in a "obscure" TXT file somewhere, its really hard to figure out what they do and what other capabilities there are. For example the whole xcontrol TXT could also be a single page in the Markup/XML and PDF. Again simplicity and decluttering is good, but XTB is complicated enough, so I would never have checked out that xcontrol file.

awvwgk commented 4 years ago

Unfortunately, there seems to be no easy way to include the asciidoc source (“obscure txt”) in read-the-docs with sphinx. So it is a technical limitation of the software we are using for the documentation prohibiting us to include this file.

The asciidoc source itself can be easily exported to PDF, HTML and roff (for man pages), but this is only supported in a different documentation framework.

awvwgk commented 4 years ago

On a related note, I'm just toying around with GH actions for building docs in DFTB+, which in fact yields a downloadable PDF file: https://github.com/dftbplus/dftbplus/pull/393, so this is maybe something I can setup for the man pages in xtb as well.

It is not on read-the-docs, but it would be easier available.