Documentation does not compile locally: Unfinished work in Documentation project?

[stefjoosten]

What happened

I tried to generate documentation locally, so I could do some work in organizing this stuff. However, the documentation failed to generate.

What I expected

I expected to generate a local Docusaurus website, so I could do some work on documentation

Version of Ampersand that was used

I was using version 4.7.1. in the branch main in commit AmpersandTarski/AmpersandTarski.github.io@3afea042965aa20d69a3de76168468b840445104.

Steps to reproduce

1. Navigate to the directory in which the documentation resides:

   sjo00577@BA92-VYF9TXMD9G git %
   cd AmpersandTarski.github.io
   sjo00577@BA92-VYF9TXMD9G AmpersandTarski.github.io % 

2. compile the documentation locally:

   docker compose up -d

3. docker worked hard to get it done. In the end, it failed with the following log:

   #0 28.25 - TheToolsWeUse/SUMMARY
   #0 28.25 - TheToolsWeUse/tools-used-in-the-ampersand-project
   #0 28.25 Error: DocNavbarItem: couldn't find any doc with id "https://github.com/AmpersandTarski/Ampersand/docs/README.md" in version current".
   #0 28.25 Available doc ids are:
   #0 28.25 - Ampersand/architecture-of-an-ampersand-application/backend-framework
   #0 28.25 - Ampersand/architecture-of-an-ampersand-application/extensions/README
   #0 28.25 - Ampersand/architecture-of-an-ampersand-application/extensions/the-execengine
   #0 28.25 - Ampersand/architecture-of-an-ampersand-application/hooks
   #0 28.25 - Ampersand/architecture-of-an-ampersand-application/README
   #0 28.25 - Ampersand/Conceptual/Automated Rules
   #0 28.25 - Ampersand/Conceptual/theory
   #0 28.25 - Ampersand/Conceptual/why-declarative
   #0 28.25 - Ampersand/configuring-your-application
   #0 28.25 - Ampersand/doc[ERROR] Unable to build website for locale en.
   #0 28.29 [ERROR] Error: Failed to compile with errors.
   #0 28.29     at /app/node_modules/@docusaurus/core/lib/webpack/utils.js:180:24
   #0 28.29     at /app/node_modules/webpack/lib/MultiCompiler.js:554:14
   #0 28.29     at processQueueWorker (/app/node_modules/webpack/lib/MultiCompiler.js:491:6)
   #0 28.29     at process.processTicksAndRejections (node:internal/process/task_queues:77:11)
   ------
   failed to solve: executor failed running [/bin/sh -c npm run build]: exit code: 1
   sjo00577@BA92-VYF9TXMD9G AmpersandTarski.github.io %

   Apparently, it cannot find the file "https://github.com/AmpersandTarski/Ampersand/docs/README.md".

Then, I ran a build run (should be superfluous though, but it might yield some diagnostic info):

sjo00577@BA92-VYF9TXMD9G AmpersandTarski.github.io % docker compose build       
[+] Building 285.9s (4/5)                                                                                                                                                 
 => [internal] load build definition from Dockerfile                                                                                                                 0.0s
 => => transferring dockerfile: 32B                                                                                                                                  0.0s
 => [internal] load .dockerignore                                                                                                                                    0.0s
[+] Building 286.0s (4/5)                                                                                                                                                 
 => [internal] load build definition from Dockerfile                                                                                                                 0.0s
 => => transferring dockerfile: 32B                                                                                                                                  0.0s
 => [internal] load .dockerignore                                                                                                                                    0.0s
[+] Building 952.7s (5/5) FINISHED                                                                                                => [internal] load build definition from Dockerfile                                                                        0.0s
 => => transferring dockerfile: 32B                                                                                         0.0s  => [internal] load .dockerignore                                                                                           0.0s
 => => transferring context: 34B                                                                                            0.0s  => [internal] load metadata for docker.io/library/nginx:stable-alpine                                                      1.8s
 => ERROR [internal] load metadata for docker.io/library/node:lts                                                         952.6s  => [auth] library/nginx:pull token for registry-1.docker.io                                                                0.0s
------
 > [internal] load metadata for docker.io/library/node:lts:
------
failed to solve: rpc error: code = Unknown desc = failed to solve with frontend dockerfile.v0: failed to create LLB definition: failed to do request: Head "https://registry-1.docker.io/v2/library/node/manifests/lts": read tcp 192.168.65.3:63732->192.168.65.128:3128: read: connection timed out
sjo00577@BA92-VYF9TXMD9G AmpersandTarski.github.io %    

[stefjoosten]

Analysis

I inspected the git repo AmpersandTarski.github.io and this is what I saw:

So obviously, I switched to branch feature/drafts and ran docker compose up -d again. Now, lo and behold, a Docusaurus site appeared on localhost:

However, there is a problem here too if you look at the Ampersand documentation, you will see a link to the docs on the left side of the navigation bar:

This link is missing in the localhost site. So, I still have nothing to work on locally...

Maybe, this branch is not finished yet? That might explain why it was not pushed to the main branch...

[hanjoosten]

I had a look, I guess this commit it the culprit: https://github.com/AmpersandTarski/AmpersandTarski.github.io/commit/3afea042965aa20d69a3de76168468b840445104 This is the result: https://github.com/AmpersandTarski/AmpersandTarski.github.io/actions/runs/3394888958/jobs/5644035769

[stefjoosten]

Indeed, my own commit has caused this bug. Mea Culpa!

I have reversed this commit and pushed it straight into the main branch of AmpersandTarski.github.io.