Merge pull request #151 from cgay/use-packages

Use packages instead of being a submodule of opendylan
dylan-lang · May 6, 2024 · 7cd29e6 · 7cd29e6
2 parents 4d039f3 + 4174b0f
commit 7cd29e6
Show file tree

Hide file tree

Showing 22 changed files with 122 additions and 116 deletions.
diff --git a/documentation/website/.gitmodules b/documentation/website/.gitmodules
@@ -1,3 +0,0 @@
-[submodule "sphinx-extensions"]
-	path = sphinx-extensions
-	url = https://github.com/dylan-lang/sphinx-extensions.git

diff --git a/documentation/website/README.rst b/documentation/website/README.rst
@@ -3,70 +3,57 @@ This is the Open Dylan website.
 It is built using `Sphinx <https://www.sphinx-doc.org/>`_.  All content is
 written using ReStructured Text with Sphinx extensions.
 
-Preparation
-===========
+Installation
+============
 
-Installing system dependencies
-------------------------------
+Some system dependencies need to be satisfied first.  On a Debian-derivative
+this should work::
 
-Some system dependencies need to be satisfied first:
+    sudo apt install git graphviz make python3
 
-- Python 3 and its package manager pip3. (It may also be installed as just
-  "pip", but check whether that installs Python 2 packages.)
-- Git
-- Make
+Install a Python3 virtual environment and use ``pip`` rather than the ``apt``
+Python packages, which are sometimes very out-of-date. ::
 
-On a Debian-derivative, they're quite easy to fetch::
+    python3 -m venv /opt/python3-venv
+    export PATH=/opt/python3-venv/bin:${PATH}
+    pip install Sphinx furo
 
-    sudo apt install python3 python3-pip git make
+The next step is fetching the repository and its dependencies::
 
-Getting the source
-------------------
+    git clone https://github.com/dylan-lang/website.git
+    cd website
+    deft update    # Install Dylan package dependencies
 
-The next step is fetching the repository and its submodule::
+Building the site
+=================
 
-    git clone --recursive https://github.com/dylan-lang/website.git  # or your fork
+Simply run the :file:`update.sh` script, specifying where you want the HTML
+files to be generated::
 
-Note that for now the "opendylan" repository is a submodule and it (along with
-its own submodules) is rather large.
+    update.sh /tmp/opendylan.org
 
-Installing Sphinx and the Furo Theme
-------------------------------------
+The first time you run :file:`update.sh`, it will build the `gendoc
+<https://github.com/dylan-lang/gendoc>`_ executable, which takes a bit longer.
 
-Now you need the Python dependencies. The easiest way to do this is to use
-``pip3``::
+.. note:: Currently the downloads directory is still maintained by hand. When
+          building the live site the first time, copy the files from the old
+          location.
 
-    sudo pip3 install -U Sphinx furo
+Testing
+=======
 
-You may also need ``python-dateutil``.
+The generated site will be in the output directory you specified. Run a local
+server using that directory as a static site. For example::
 
-    sudo pip3 install python-dateutil
+    python3 -m http.server --directory /tmp/opendylan.org
 
-Building
-========
-
-Building the website is easy on a system with ``make``::
-
-    make html
-
-If you are on Windows, there is a ``make.bat`` as well. It currently requires
-that you run it with an argument::
-
-    make.bat html  # Best of luck! This hasn't been tested in ages.
-
-The generated site will be in ``build/html``. For the stylesheets and
-JavaScript to load correctly, we suggest running a local webserver
-pointing to this directory::
-
-    python3 -m http.server --directory build/html
-
-or you can eat our own Dylan dogfood and run our HTTP server! ::
+For bonus points, you can eat our own dogfood and run the Dylan HTTP server
+instead::
 
     git clone --recursive https://github.com/dylan-lang/http
     cd http
     make install
-    cd ...back to website dir...
-    http-server --directory build/html
+    http-server --directory /tmp/opendylan.org
 
 Link Validation
 ---------------

diff --git a/documentation/website/dylan-package.json b/documentation/website/dylan-package.json
@@ -0,0 +1,16 @@
+{
+    "name": "website",
+    "version": "0.1.0",
+    "description": "The opendylan.org website and tools to build it.",
+    "contact": "[email protected]",
+    "keywords": ["documentation"],
+    "dependencies": [],
+    "dev-dependencies": [
+        "dylan-reference-manual",
+        "dylan-programming-book",
+        "gendoc",
+        "opendylan",
+        "sphinx-extensions"
+    ],
+    "url": "https://github.com/dylan-lang/website"
+}
diff --git a/documentation/website/source/building-with-duim b/documentation/website/source/building-with-duim
@@ -1 +1 @@
-../../building-with-duim/source
+../_packages/opendylan/current/src/documentation/building-with-duim
diff --git a/documentation/website/source/community/index.rst b/documentation/website/source/community/index.rst
@@ -15,7 +15,7 @@ GitHub <https://gist.github.com>`_ and paste a link to it.
 .. _contribute:
 
 How to Contribute
-  The :doc:`Hacker Guide <../hacker-guide/index>` has details on how to
+  The :doc:`Hacker Guide <../hacker-guide/source/index>` has details on how to
   contribute to the project.
 
 Report Bugs

diff --git a/documentation/website/source/conf.py b/documentation/website/source/conf.py
@@ -3,7 +3,7 @@
 
 import os
 import sys
-sys.path.insert(0, os.path.abspath('../../sphinx-extensions/sphinxcontrib'))
+sys.path.insert(0, os.path.abspath('../_packages/sphinx-extensions/current/src/sphinxcontrib'))
 extensions = [
     'dylan.domain',
     'sphinx.ext.graphviz',
@@ -38,9 +38,5 @@
 templates_path = ['_templates']
 
 exclude_patterns = [
-    # Omit duplicate docs and docs in submodules...
     '**/sphinx_rtd_theme/**',
-    'opendylan/sources/**',
-    'opendylan/*.rst',
-    'opendylan/**/README.rst',
 ]
diff --git a/documentation/website/source/corba-guide b/documentation/website/source/corba-guide
@@ -1 +1 @@
-../../corba-guide/source
+../_packages/opendylan/current/src/documentation/corba-guide
diff --git a/documentation/website/source/documentation/index.rst b/documentation/website/source/documentation/index.rst
@@ -8,7 +8,7 @@ Learn Dylan
 :doc:`../about/index`
     A quick overview of the language with examples of major features.
 
-:doc:`../intro-dylan/index`
+:doc:`../intro-dylan/source/index`
     This tutorial is written primarily for those with solid programming
     experience in C++ or another object-oriented, static language. It
     provides a gentler introduction to Dylan than does the `Dylan Reference
@@ -17,15 +17,15 @@ Learn Dylan
 `Dylan Programming Guide`_ [`pdf <https://opendylan.org/books/dpg/DylanProgramming.pdf>`__] [`epub <https://opendylan.org/books/dpg/DylanProgramming.epub>`__]
     A book length Dylan tutorial.
 
-:doc:`../getting-started-cli/index`
+:doc:`../getting-started-cli/source/index`
     Describes development using the Open Dylan command line tools
     and editor integration (like emacs). This is mainly for
     Linux, FreeBSD, and macOS users.
 
-:doc:`../getting-started-ide/index`
+:doc:`../getting-started-ide/source/index`
     Describes Open Dylan's integrated development environment (Windows only).
 
-:doc:`../building-with-duim/index`
+:doc:`../building-with-duim/source/index`
     Describes how to use DUIM (Dylan User Interface Manager),
     the portable window programming toolkit. (Windows only.)
 
@@ -35,15 +35,15 @@ References
 `Dylan Reference Manual`_ (`Errata`_)
     The official definition of the Dylan language and standard library.
 
-:doc:`../library-reference/index`
+:doc:`../library-reference/source/index`
     Reference docs for core libraries packaged with Open Dylan.
 
-:doc:`../duim-reference/index`
+:doc:`../duim-reference/source/index`
     Describes the libraries forming DUIM (Dylan User Interface Manager),
     the portable window programming toolkit. It complements
     Building Applications Using DUIM. (Currently Windows only.)
 
-:doc:`../corba-guide/index`
+:doc:`../corba-guide/source/index`
     A tutorial and reference for CORBA interoperability using the Open
     Dylan ORB.
 
@@ -132,18 +132,18 @@ For Open Dylan Developers
 .. note:: Notes and materials useful to those working on Open Dylan itself or
           those who have an interest in the low level details.
 
-:doc:`../hacker-guide/index`
+:doc:`../hacker-guide/source/index`
     A work in progress to help out people who are hacking on Open Dylan itself.
 
-:doc:`../style-guide/index`
+:doc:`../style-guide/source/index`
     Notes and thoughts on how to format your Dylan code. This is the style
     guide that we aspire to adhere to in the Open Dylan sources.
 
 :doc:`../proposals/index`
     A series of proposals for improvements to the Open Dylan
     implementation and related libraries.
 
-:doc:`../release-notes/index`
+:doc:`../release-notes/source/index`
     Notes on new features and bug fixes in each release of Open Dylan.
 
 
@@ -160,11 +160,11 @@ For Open Dylan Developers
    News <../news/index>
    Cheat Sheets <cheatsheets/index>
    Publications <publications>
-   Intro to Dylan <../intro-dylan/index>
-   CORBA Guide <../corba-guide/index>
-   DUIM Guide <../building-with-duim/index>
-   DUIM Reference <../duim-reference/index>
-   Getting Started / IDE <../getting-started-ide/index>
-   Release Notes <../release-notes/index>
+   Intro to Dylan <../intro-dylan/source/index>
+   CORBA Guide <../corba-guide/source/index>
+   DUIM Guide <../building-with-duim/source/index>
+   DUIM Reference <../duim-reference/source/index>
+   Getting Started / IDE <../getting-started-ide/source/index>
+   Release Notes <../release-notes/source/index>
    Sphinx Extensions <../../sphinx-extensions/documentation/source/index>
-   Style Guide <../style-guide/index>
+   Style Guide <../style-guide/source/index>
diff --git a/documentation/website/source/duim-reference b/documentation/website/source/duim-reference
@@ -1 +1 @@
-../../duim-reference/source
+../_packages/opendylan/current/src/documentation/duim-reference
diff --git a/documentation/website/source/getting-started-cli b/documentation/website/source/getting-started-cli
@@ -1 +1 @@
-../../getting-started-cli/source
+../_packages/opendylan/current/src/documentation/getting-started-cli
diff --git a/documentation/website/source/getting-started-ide b/documentation/website/source/getting-started-ide
@@ -1 +1 @@
-../../getting-started-ide/source
+../_packages/opendylan/current/src/documentation/getting-started-ide
diff --git a/documentation/website/source/hacker-guide b/documentation/website/source/hacker-guide
@@ -1 +1 @@
-../../hacker-guide/source
+../_packages/opendylan/current/src/documentation/hacker-guide
diff --git a/documentation/website/source/index.rst b/documentation/website/source/index.rst
@@ -33,13 +33,13 @@ how to define libraries and modules right away.
 
 Then move on to one of these in-depth guides:
 
-* :doc:`intro-dylan/index` provides a high-level overview of language
+* :doc:`intro-dylan/source/index` provides a high-level overview of language
   features.
 * `Dylan Programming Guide`_ is a book length Dylan tutorial.
 
 The `Dylan Reference Manual`_, besides being the official language definition,
 has an excellent, very brief `introduction
-<https://opendylan.org/books/drm/Introduction>`_ describing the language
+<books/drm/Introduction>`_ describing the language
 background and goals.
 
 Or explore :doc:`all the docs <documentation/index>`, including cheat sheets,
@@ -83,15 +83,15 @@ articles, and all the library docs.
 
    Get Involved <community/index>
    Download <download/index>
-   Hacker Guide <hacker-guide/index>
+   Hacker Guide <hacker-guide/source/index>
    Enhancement Proposals <proposals/index>
 
 .. toctree::
    :caption: Learning
    :hidden:
 
    Tour of Dylan <about/index>
-   Getting Started Guide <getting-started-cli/index>
+   Getting Started Guide <getting-started-cli/source/index>
    Dylan Programming Guide <https://opendylan.org/books/dpg/>
    Dylan Playground <https://play.opendylan.org>
 
@@ -105,6 +105,6 @@ articles, and all the library docs.
 
    Dylan Reference Manual <https://opendylan.org/books/drm/>
    Package Docs <package/index>
-   Open Dylan Libraries <library-reference/index>
+   Open Dylan Libraries <library-reference/source/index>
    All Documentation <documentation/index>
    Full Index <genindex>
diff --git a/documentation/website/source/intro-dylan b/documentation/website/source/intro-dylan
@@ -1 +1 @@
-../../intro-dylan/source
+../_packages/opendylan/current/src/documentation/intro-dylan
diff --git a/documentation/website/source/library-reference b/documentation/website/source/library-reference
@@ -1 +1 @@
-../../library-reference/source
+../_packages/opendylan/current/src/documentation/library-reference
diff --git a/documentation/website/source/man-pages b/documentation/website/source/man-pages
@@ -1 +1 @@
-../../man-pages/source
+../_packages/opendylan/current/src/documentation/man-pages
diff --git a/documentation/website/source/release-notes b/documentation/website/source/release-notes
@@ -1 +1 @@
-../../release-notes/source
+../_packages/opendylan/current/src/documentation/release-notes
diff --git a/documentation/website/source/sphinx-extensions b/documentation/website/source/sphinx-extensions
@@ -0,0 +1 @@
+../_packages/sphinx-extensions/current/src
diff --git a/documentation/website/source/style-guide b/documentation/website/source/style-guide
@@ -1 +1 @@
-../../style-guide/source
+../_packages/opendylan/current/src/documentation/style-guide
diff --git a/documentation/website/sphinx-extensions b/documentation/website/sphinx-extensions
diff --git a/documentation/website/update-opendylan.org.sh b/documentation/website/update-opendylan.org.sh
@@ -7,19 +7,15 @@ exec > $logfile 2>&1
 
 exe_dir="$(realpath $(dirname $0))"
 
-repo_dir=/root/deploy-opendylan.org
-gendoc_exe=${repo_dir}/gendoc/_build/bin/gendoc
 dest_dir=/var/www/opendylan.org
 
-# Update opendylan and website submodule first so we get any changes
-# to the update.sh script.
-cd ${repo_dir}/opendylan
+# Update the repo first so we get any changes to the update.sh script,
+# dependencies, etc.
 git pull --rebase origin master
-git submodule update --init --recursive
 
-${exe_dir}/update.sh "${dest_dir}" "${repo_dir}" "${gendoc_exe}"
+${exe_dir}/update.sh "${dest_dir}"
 
-echo "Done updating opendylan.org"
+echo "Done updating opendylan.org in ${dest_DIR}."
 bzip2 $logfile
 # Keep 10 days of logs.
 find /var/log -name 'update-opendylan.org.*' -mtime +10 -print -exec rm {} \;