Merge pull request #268 from ArtifexSoftware/update-docs-theme

Documentation: renames base folder and adds new theme.

.readthedocs.yaml

@@ -17,7 +17,7 @@ build:
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
-   configuration: doc/conf.py
+   configuration: docs/conf.py
 
 # If using Sphinx, optionally build your docs in additional formats such as PDF
 #formats:
@@ -26,4 +26,4 @@ sphinx:
 # Optionally declare the Python requirements required to build your docs
 python:
    install:
-   - requirements: doc/requirements.txt
+   - requirements: docs/requirements.txt

docs/README.md

@@ -0,0 +1,34 @@
+# pdf2docx documentation
+
+Welcome to the **pdf2docx** documentation. This documentation relies on [Sphinx](https://www.sphinx-doc.org/en/master/) to publish HTML docs from markdown files written with [restructured text](https://en.wikipedia.org/wiki/ReStructuredText) (RST).
+
+
+## Sphinx version
+
+This README assumes you have [Sphinx v5.0.2 installed](https://www.sphinx-doc.org/en/master/usage/installation.html) on your system.
+
+
+## Updating the documentation
+
+Within `docs` update the associated restructured text (`.rst`) files. These files represent the corresponding document pages. 
+
+
+## Building HTML documentation
+
+- Ensure you have the `furo` theme installed:
+
+`pip install furo`
+
+Furo theme, Copyright (c) 2020 Pradyun Gedam <[email protected]>, thank you to:
+
+https://github.com/pradyunsg/furo/blob/main/LICENSE
+
+- From the "docs" location run:
+
+`sphinx-build -b html . build/html`
+
+This then creates the HTML documentation within `build/html`. 
+
+> Use: `sphinx-build -a -b html . build/html` to build all, including the assets in `_static` (important if you have updated CSS).
+
+For full details see: [Using Sphinx](https://www.sphinx-doc.org/en/master/usage/index.html)

docs/_static/custom.css

@@ -0,0 +1,207 @@
+/* main document page: ensures pages fit to the available width and height */
+.wy-nav-content {
+    min-width: 100%;
+    min-height: 100vh;
+}
+
+/* Accessibility: Artifex color for main document links */
+.wy-nav-content a {
+    color: #007aff;
+}
+
+/* Artifex blue color for background elements */
+.wy-side-nav-search, .wy-nav-top {
+    background-color: #007aff;
+}
+
+/* Accessibility: ensures that the version number is readable against the background color */
+.wy-side-nav-search>div.version {
+    color:hsla(0,0%,100%,1);
+}
+
+.htmltag {
+    padding: 2px 5px;
+    background-color: #fbff68;
+    border-radius: 4px;
+    border: 1px solid #222;
+    color:#000;
+}
+
+.discordLink {
+    display:flex;
+    justify-content:flex-end;
+    margin:0;
+    padding:0;
+    font-size: 13px;
+}
+
+.discordLink img {
+    width: 30px;
+    height: 30px;
+    margin-left: 8px;
+}
+
+.feedbackLink {
+    display:flex;
+    justify-content:flex-end;
+    margin:0 0 10px;
+    padding:0;
+    font-size: 13px;
+}
+
+.intro-title {
+    font-size: 22px;
+    margin: 0 0 20px 0;
+}
+
+h1 {
+    padding: 10px !important;
+    background-color: #007aff !important;
+    color: #fff !important;
+    border-radius: 5px !important;
+    margin-top: 20px !important;
+    margin-left: -10px !important;
+}
+
+cite {
+    font-weight: bold;
+    font-style: normal;
+}
+
+.red-color {
+    color: #cc0000;
+}
+
+.orange-color {
+    color: #ff6600;
+}
+
+.green-color {
+    color: #00cc00;
+}
+
+button.cta {
+    -webkit-appearance: none;
+    -moz-appearance: none;
+    border:0;
+    text-transform:uppercase;
+    border-radius:5px;
+    font-size:16px;
+    font-weight:500;
+    min-height:40px;
+    line-height:40px;
+    padding: 0 15px;
+    color:#fff;
+    cursor:pointer;
+}
+
+button.cta.orange {
+    width:auto;
+    background-image: linear-gradient(to right, #ea5842, #ec6343, #ed6d45, #ef7747, #f0804a) !important;
+}
+
+button.cta.orange:hover {
+    background:#ea5842 !important;
+}
+
+button.cta a {
+    color:#fff !important;
+}
+
+.footer-version {
+    font-weight: bold;
+    font-size: 12px;
+    color: #999;
+}
+
+
+/*** Furo theme overrides ***/
+/* This is to do with hiding the Furo link text and the "Made with" text */
+.bottom-of-page .left-details {
+    font-size:0;
+}
+
+.bottom-of-page .left-details a {
+    display:none;
+}
+
+/* Now ensure that the other copyright text is visible here */
+.bottom-of-page .left-details > * {
+    font-size:12px;
+}
+
+.sidebar-brand-text {
+    font-size: 13px;
+    padding: 0;
+    margin: 0;
+}
+
+.sidebar-logo {
+    width: 60px;
+    height: 60px;
+}
+
+.sidebar-container {
+    margin: 0;
+    padding: 0;
+}
+
+.sidebar-container .sidebar-search-container {
+    display: none;
+}
+
+.sidebar-search-container.top {
+    /*position:sticky;
+    top:10px;*/
+    border-radius: 20px;
+    border: solid #333 1px;
+    background-color: #fff;
+}
+
+.sidebar-search-container.top .sidebar-search {
+    border-top: 0 !important;
+    border-bottom: 0 !important;
+}
+
+/* really important ! */
+.sidebar-search {
+    color: #000 !important;
+}
+
+.toc-drawer .toc-title {
+    font-weight: bold;
+    text-decoration: underline;
+}
+
+:target>h1:first-of-type, span:target~h1:first-of-type {
+    background-color: #007aff !important;
+    color: #fff !important;
+    padding-top: 40px; /* accomodates header search blocking target */
+    margin-top: -40px;
+}
+
+
+:target>h2:first-of-type, :target>h3:first-of-type,
+:target>h4:first-of-type, :target>h5:first-of-type, :target>h6:first-of-type,
+span:target~h2:first-of-type, span:target~h3:first-of-type,
+span:target~h4:first-of-type, span:target~h5:first-of-type, span:target~h6:first-of-type {
+    background-color: transparent !important;
+    padding-top: 40px; /* accomodates header search blocking target */
+    margin-top: -40px;
+    text-decoration: underline;
+}
+
+
+/* Dark mode colors */
+@media (prefers-color-scheme: dark) {
+
+
+
+}
+
+/* small screens */
+@media all and (max-width : 550px)  {
+    .discordLink img {
+        display: none;
+    }
+}

doc/conf.py → docs/conf.py

@@ -12,35 +12,41 @@
 #
 import os
 import sys
+import datetime
 sys.path.insert(0, os.path.abspath("../pdf2docx/"))
 
 
 # -- Project information -----------------------------------------------------
 
 project = 'pdf2docx'
-copyright = '2023, Artifex'
+thisday = datetime.date.today()
+copyright = str(thisday.year) + ", Artifex"
 author = 'Artifex Software, Inc.'
 
-# The full version, including alpha/beta/rc tags
-# read version number from version.txt, otherwise alpha version
-# Github CI can create version.txt dynamically.
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The full version, including alpha/beta/rc tags.
 def get_version(fname):
     if os.path.exists(fname):
         with open(fname, 'r') as f:
-            version = f.readline().strip()
+            release = f.readline().strip()
     else:
-        version = 'alpha'
+        release = 'alpha'
+
+    return release
 
-    return version
-release = get_version('../version.txt')
+version = get_version('../version.txt')
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinxcontrib.apidoc'
+    'sphinxcontrib.apidoc',
+    'sphinx_copybutton'
 ]
 
 apidoc_module_dir = '../pdf2docx'
@@ -63,14 +69,22 @@ def get_version(fname):
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-# html_theme = 'alabaster'
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'furo'
 
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ['_static']
+html_static_path = ['_static']
+
+# A list of CSS files. The entry must be a filename string or a tuple containing
+# the filename string and the attributes dictionary. The filename must be
+# relative to the html_static_path, or a full URI
+html_css_files = ["custom.css"]
+
+
+html_favicon = "_static/PyMuPDF.ico"
+
 
 # -- Options for LaTeX output ---------------------------------------------
 latex_elements = {

docs/footer.rst

@@ -0,0 +1,31 @@
+.. raw:: html
+
+   <div class="feedbackLink"><a id="feedbackLinkBottom" target=_blank>Do you have any feedback on this page?</b></a></div>
+
+   <script>
+        var url_string = window.location.href;
+        var a = document.getElementById('feedbackLinkBottom');
+        a.setAttribute("href", "https://artifex.com/contributor/feedback.php?utm_source=rtd-pdf2docx&utm_medium=rtd&utm_content=header-link&url="+url_string);
+    </script>
+
+----
+
+.. raw:: html
+
+   <p style="color:#999" id="footerDisclaimer">This software is provided AS-IS with no warranty, either express or implied. This software is distributed under license and may not be copied, modified or distributed except as expressly authorized under the terms of that license. Refer to licensing information at <a href="https://www.artifex.com?utm_source=rtd-pdf2docx&utm_medium=rtd&utm_content=footer-link">artifex.com</a> or contact Artifex Software Inc., 39 Mesa Street, Suite 108A, San Francisco CA 94129, United States for further information.</p>
+
+
+.. rst-class:: footer-version
+
+  This documentation covers all versions up to |version|.
+
+
+.. note - this ensures that the Sphinx build system will pull in the image (as it is referenced in an RST file) to _images,
+   we don't want to display it via rst markup due to limitations (hence width:0), however we do want it available for our raw HTML
+   which we use in header.rst.
+
+.. image:: images/discord-mark-blue.svg
+          :alt: Discord logo
+          :width: 0
+          :height: 0
+          :target: https://discord.gg/TSpYGBW4eq