From ae09d3aebee6731a5e9e9148d56623ffef686034 Mon Sep 17 00:00:00 2001 From: Arnau Casau <47946624+arnaucasau@users.noreply.github.com> Date: Thu, 9 May 2024 17:46:44 +0200 Subject: [PATCH 1/5] Update README.md --- README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.md b/README.md index dc9917fcd45..424146210b1 100644 --- a/README.md +++ b/README.md @@ -79,6 +79,18 @@ The preview application does not include the top nav bar. Instead, navigate to t Warning: `./start` does not check if there is a new version of the docs application available. Run `docker pull qiskit/documentation` to update to the latest version of the app. +### API docs authors: How to preview your changes + +API docs authors can preview their changes to one of the APIs by following these steps: + +1. Go to your `qiskit/documentation` folder +2. Create a folder named `.sphinx-artifacts//./artifact` , or use the one that already exists if you have generated that version before. +5. Move the HTML output of Sphinx, including all the folders (e.g., apidoc and stubs) into the artifact folder +6. Run `npm run gen-api -- -p qiskit -v 1.1.0 --skip-download` +7. Open Rancher Desktop (not necessary for Linux) +8. Execute `./start` +9. Go to http://localhost:3000 + ## Preview the docs in PRs Contributors with write access to this repository can use live previews of the docs: GitHub will deploy a website using your changes. From 78e934c05d165ddaadf550ae3e63ca949c692623 Mon Sep 17 00:00:00 2001 From: Arnau Casau <47946624+arnaucasau@users.noreply.github.com> Date: Thu, 9 May 2024 17:55:44 +0200 Subject: [PATCH 2/5] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 424146210b1..67c5a57c853 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ Warning: `./start` does not check if there is a new version of the docs applicat API docs authors can preview their changes to one of the APIs by following these steps: 1. Go to your `qiskit/documentation` folder -2. Create a folder named `.sphinx-artifacts//./artifact` , or use the one that already exists if you have generated that version before. +2. Create a folder named `.sphinx-artifacts//./artifact`, or use the one that already exists if you have generated that version before. 5. Move the HTML output of Sphinx, including all the folders (e.g., apidoc and stubs) into the artifact folder 6. Run `npm run gen-api -- -p qiskit -v 1.1.0 --skip-download` 7. Open Rancher Desktop (not necessary for Linux) From f604761ccb8a5f06e90f0ff6a813b769debe2a85 Mon Sep 17 00:00:00 2001 From: Arnau Casau <47946624+arnaucasau@users.noreply.github.com> Date: Thu, 9 May 2024 18:00:19 +0200 Subject: [PATCH 3/5] Update README.md --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 67c5a57c853..3d8e7bebc2d 100644 --- a/README.md +++ b/README.md @@ -85,11 +85,11 @@ API docs authors can preview their changes to one of the APIs by following these 1. Go to your `qiskit/documentation` folder 2. Create a folder named `.sphinx-artifacts//./artifact`, or use the one that already exists if you have generated that version before. -5. Move the HTML output of Sphinx, including all the folders (e.g., apidoc and stubs) into the artifact folder -6. Run `npm run gen-api -- -p qiskit -v 1.1.0 --skip-download` -7. Open Rancher Desktop (not necessary for Linux) -8. Execute `./start` -9. Go to http://localhost:3000 +3. Move the HTML output of Sphinx, including all the folders (e.g., apidoc and stubs) into the artifact folder +4. Run `npm run gen-api -- -p qiskit -v 1.1.0 --skip-download` +5. Open Rancher Desktop (not necessary for Linux) +6. Execute `./start` +7. Go to http://localhost:3000 ## Preview the docs in PRs From 73523cdc9b722244c45e42e978bb47775ef7d1ed Mon Sep 17 00:00:00 2001 From: Arnau Casau <47946624+arnaucasau@users.noreply.github.com> Date: Fri, 10 May 2024 14:40:11 +0200 Subject: [PATCH 4/5] Add the `-a` parameter to the readme --- README.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 3d8e7bebc2d..fa0c154475c 100644 --- a/README.md +++ b/README.md @@ -81,15 +81,12 @@ Warning: `./start` does not check if there is a new version of the docs applicat ### API docs authors: How to preview your changes -API docs authors can preview their changes to one of the APIs by following these steps: - -1. Go to your `qiskit/documentation` folder -2. Create a folder named `.sphinx-artifacts//./artifact`, or use the one that already exists if you have generated that version before. -3. Move the HTML output of Sphinx, including all the folders (e.g., apidoc and stubs) into the artifact folder -4. Run `npm run gen-api -- -p qiskit -v 1.1.0 --skip-download` -5. Open Rancher Desktop (not necessary for Linux) -6. Execute `./start` -7. Go to http://localhost:3000 +API docs authors can preview their changes to one of the APIs by using the `-a` parameter to specify the path to the docs folder: + +1. Run `npm run gen-api -- -p -v -a `. +2. Open Rancher Desktop (not necessary for Linux). +3. Execute `./start` as explained in the previous section. +4. Go to http://localhost:3000 in your browser. ## Preview the docs in PRs From c4b190144055009445b24106e5ee78b7907610cb Mon Sep 17 00:00:00 2001 From: Arnau Casau <47946624+arnaucasau@users.noreply.github.com> Date: Fri, 10 May 2024 15:15:22 +0200 Subject: [PATCH 5/5] feedback --- README.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index fa0c154475c..2775f65fea7 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,10 @@ npm install ## Preview the docs locally -Run `./start` in your terminal, then open http://localhost:3000 in your browser. +You can preview the docs locally by following these two steps: + +1. Ensure Docker is running. For example, open Rancher Desktop. +2. Run `./start` in your terminal, and open http://localhost:3000 in your browser. The preview application does not include the top nav bar. Instead, navigate to the folder you want with the links in the home page. You can return to the home page at any time by clicking "IBM Quantum Documentation Preview" in the top-left of the header. @@ -84,9 +87,7 @@ Warning: `./start` does not check if there is a new version of the docs applicat API docs authors can preview their changes to one of the APIs by using the `-a` parameter to specify the path to the docs folder: 1. Run `npm run gen-api -- -p -v -a `. -2. Open Rancher Desktop (not necessary for Linux). -3. Execute `./start` as explained in the previous section. -4. Go to http://localhost:3000 in your browser. +2. Execute `./start` and open up `http://localhost:3000`, as explained in the prior section. ## Preview the docs in PRs