Various improvements to the “getting started” part
ClosedPublic
Actions

Authored by lunar on Sep 15 2022, 6:29 PM.

Details

Reviewers

Group Reviewers

Commits

rDDOCa3c8cca7a423: Update links and wordings in the developer setup
rDDOCc11d93ef2989: Make “Run your own” tutorial more coherent
rDDOC7d3368e31a99: Use a single command to disable and stop manually started services
rDDOC0e9b12c292e4: Add an introduction on the “Getting started” cover page

Summary

Add an introduction on the “Getting started” cover page.
Make “Run your own” tutorial more coherent.
Use a single command to disable and stop manually started services.
Update links and wordings in the developer setup.

Diff Detail

Repository

rDDOC Development documentation

Branch

master

Lint

No Linters Available

Unit

No Unit Test Coverage

Build Status

Buildable 31577
Build 49387: Phabricator diff pipeline on Jenkins for swh-docs	Jenkins console · Jenkins
Build 49386: arc lint + arc unit

Event Timeline

lunar created this revision.Sep 15 2022, 6:29 PM

Herald added a reviewer: Reviewers. · View Herald TranscriptSep 15 2022, 6:29 PM

Build has FAILED

Patch application report for D8494 (id=30585)

Rebasing onto 5cef6a88d8...

Current branch diff-target is up to date.

Changes applied before test

commit 632a60fccd0616c1281600eb3f4f95242558b72b
Author: Jérémy Bobbio (Lunar) <lunar@softwareheritage.org>
Date:   Thu Sep 15 18:24:59 2022 +0200

    Update links and wordings in the developer setup
    
    - Use the generic `virtual environment` instead of `virtualenv` and
      point to the official Python documentation.
    - Use the internal reference to the getting started doc.
    - Mention there is tons of good tips in the documentation about
      the Docker environment.
    - Update the link to the documentation on how to submit patches.

commit f7b59765bf45b5c79a12330f1e37bf43ed94a58e
Author: Jérémy Bobbio (Lunar) <lunar@softwareheritage.org>
Date:   Thu Sep 15 18:22:26 2022 +0200

    Use a single command to disable and stop manually started services
    
    The `--now` flag to `systemctl disable` will stop (on top of disabling)
    the given services. `systemctl disable` also accepts multiple services
    as argument.
    
    We can thus replace 4 commands in the developer setup documentation by a
    single one.

commit 21fb1b850921ff4788f404e904e404a17664c31c
Author: Jérémy Bobbio (Lunar) <lunar@softwareheritage.org>
Date:   Thu Sep 15 18:17:05 2022 +0200

    Make “Run your own” tutorial more coherent
    
    The tutorial on how to “run your own Software Heritage” felt quite dry.
    Meanwhile, more details on how to start using the local
    instance were already available in the documentation on how to use
    the Docker environment.
    
    So we pull in the relevant sections from
    `swh-environment/docker/README.rst` to complement the existing tutorial.

commit 50922991143b36d4152076234cb063f2db976758
Author: Jérémy Bobbio (Lunar) <lunar@softwareheritage.org>
Date:   Thu Sep 15 18:15:06 2022 +0200

    Add an introduction on the “Getting started” cover page

Link to build: https://jenkins.softwareheritage.org/job/DDOC/job/build-on-diff/235/
See console output for more information: https://jenkins.softwareheritage.org/job/DDOC/job/build-on-diff/235/console

Harbormaster returned this revision to the author for changes because remote builds failed.Sep 15 2022, 6:42 PM

Harbormaster failed remote builds in B31577: Diff 30585!

Try to fix bad reference

Fix bad reference (and upload all commits this time)

Build is green

Patch application report for D8494 (id=30586)

Could not rebase; Attempt merge onto 5cef6a88d8...

Updating 5cef6a8..a3c8cca
Fast-forward
 docs/developer-setup.rst       |  29 +++----
 docs/getting-started.rst       | 183 +++++++++++++++++++++++++++++++++--------
 docs/getting-started/index.rst |  11 +++
 3 files changed, 173 insertions(+), 50 deletions(-)

Changes applied before test

commit a3c8cca7a423bb4afb4c33ff9c6f956dbf89bbcf
Author: Jérémy Bobbio (Lunar) <lunar@softwareheritage.org>
Date:   Thu Sep 15 18:24:59 2022 +0200

    Update links and wordings in the developer setup
    
    - Use the generic `virtual environment` instead of `virtualenv` and
      point to the official Python documentation.
    - Use the internal reference to the getting started doc.
    - Mention there is tons of good tips in the documentation about
      the Docker environment.
    - Update the link to the documentation on how to submit patches.

commit 7d3368e31a998384b9c58986a59c178527f77e88
Author: Jérémy Bobbio (Lunar) <lunar@softwareheritage.org>
Date:   Thu Sep 15 18:22:26 2022 +0200

    Use a single command to disable and stop manually started services
    
    The `--now` flag to `systemctl disable` will stop (on top of disabling)
    the given services. `systemctl disable` also accepts multiple services
    as argument.
    
    We can thus replace 4 commands in the developer setup documentation by a
    single one.

commit c11d93ef2989041b36f5ae4232a6adca1ae59a0e
Author: Jérémy Bobbio (Lunar) <lunar@softwareheritage.org>
Date:   Thu Sep 15 18:17:05 2022 +0200

    Make “Run your own” tutorial more coherent
    
    The tutorial on how to “run your own Software Heritage” felt quite dry.
    Meanwhile, more details on how to start using the local
    instance were already available in the documentation on how to use
    the Docker environment.
    
    So we pull in the relevant sections from
    `swh-environment/docker/README.rst` to complement the existing tutorial.

commit 0e9b12c292e4012755c86196a495c6f92005394a
Author: Jérémy Bobbio (Lunar) <lunar@softwareheritage.org>
Date:   Thu Sep 15 18:15:06 2022 +0200

    Add an introduction on the “Getting started” cover page

See https://jenkins.softwareheritage.org/job/DDOC/job/build-on-diff/236/ for more details.

Harbormaster completed remote builds in B31578: Diff 30586.Sep 15 2022, 6:58 PM

Build is green

Patch application report for D8494 (id=30587)

Rebasing onto 5cef6a88d8...

Current branch diff-target is up to date.

Changes applied before test

commit a3c8cca7a423bb4afb4c33ff9c6f956dbf89bbcf
Author: Jérémy Bobbio (Lunar) <lunar@softwareheritage.org>
Date:   Thu Sep 15 18:24:59 2022 +0200

    Update links and wordings in the developer setup
    
    - Use the generic `virtual environment` instead of `virtualenv` and
      point to the official Python documentation.
    - Use the internal reference to the getting started doc.
    - Mention there is tons of good tips in the documentation about
      the Docker environment.
    - Update the link to the documentation on how to submit patches.

commit 7d3368e31a998384b9c58986a59c178527f77e88
Author: Jérémy Bobbio (Lunar) <lunar@softwareheritage.org>
Date:   Thu Sep 15 18:22:26 2022 +0200

    Use a single command to disable and stop manually started services
    
    The `--now` flag to `systemctl disable` will stop (on top of disabling)
    the given services. `systemctl disable` also accepts multiple services
    as argument.
    
    We can thus replace 4 commands in the developer setup documentation by a
    single one.

commit c11d93ef2989041b36f5ae4232a6adca1ae59a0e
Author: Jérémy Bobbio (Lunar) <lunar@softwareheritage.org>
Date:   Thu Sep 15 18:17:05 2022 +0200

    Make “Run your own” tutorial more coherent
    
    The tutorial on how to “run your own Software Heritage” felt quite dry.
    Meanwhile, more details on how to start using the local
    instance were already available in the documentation on how to use
    the Docker environment.
    
    So we pull in the relevant sections from
    `swh-environment/docker/README.rst` to complement the existing tutorial.

commit 0e9b12c292e4012755c86196a495c6f92005394a
Author: Jérémy Bobbio (Lunar) <lunar@softwareheritage.org>
Date:   Thu Sep 15 18:15:06 2022 +0200

    Add an introduction on the “Getting started” cover page

See https://jenkins.softwareheritage.org/job/DDOC/job/build-on-diff/237/ for more details.

Harbormaster completed remote builds in B31579: Diff 30587.Sep 15 2022, 7:00 PM

lunar requested review of this revision.Sep 15 2022, 7:00 PM

vlorentz accepted this revision.Sep 15 2022, 8:24 PM

vlorentz added a subscriber: vlorentz.

vlorentz added inline comments.