diff --git a/user/images/card_basics_undraw_discoverable.svg b/user/images/card_basics_undraw_discoverable.svg new file mode 100644 --- /dev/null +++ b/user/images/card_basics_undraw_discoverable.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/user/images/card_browse_undraw_file_searching.svg b/user/images/card_browse_undraw_file_searching.svg new file mode 100644 --- /dev/null +++ b/user/images/card_browse_undraw_file_searching.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/user/images/card_contribute_undraw_dev_focus.svg b/user/images/card_contribute_undraw_dev_focus.svg new file mode 100644 --- /dev/null +++ b/user/images/card_contribute_undraw_dev_focus.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/user/images/card_interface_undraw_futuristic_interface.svg b/user/images/card_interface_undraw_futuristic_interface.svg new file mode 100644 --- /dev/null +++ b/user/images/card_interface_undraw_futuristic_interface.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/user/images/card_outreach_undraw_engineering_team.svg b/user/images/card_outreach_undraw_engineering_team.svg new file mode 100644 --- /dev/null +++ b/user/images/card_outreach_undraw_engineering_team.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/user/images/card_preserve_undraw_moving.svg b/user/images/card_preserve_undraw_moving.svg new file mode 100644 --- /dev/null +++ b/user/images/card_preserve_undraw_moving.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/user/index.rst b/user/index.rst --- a/user/index.rst +++ b/user/index.rst @@ -1,26 +1,139 @@ .. _swh-docs: -Software Heritage User documentation -==================================== +Welcome to Software Heritage documentation +========================================== -Getting started ---------------- -* :ref:`faq` -* :ref:`listers` -* :ref:`loaders` +.. grid:: 1 2 2 2 + :gutter: 3 + .. grid-item-card:: Basics + :link: landing-basics + :link-type: ref -Indices and tables -================== + .. image:: images/card_basics_undraw_discoverable.svg + :width: 69% + :align: center + :class: sd-mb-2 -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + Learn about our mission and our source code archive. Find out about how to + make your first steps with the archive. + .. button-ref:: landing-basics + :ref-type: ref + :color: primary + :expand: + + Discover Software Heritage + + .. grid-item-card:: Preserve + :link: landing-preserve + :link-type: ref + + .. image:: images/card_preserve_undraw_moving.svg + :align: center + :class: sd-mt-1 sd-mb-4 + + All the ways that source code may be added or updated in the archive. + + .. button-ref:: landing-preserve + :ref-type: ref + :color: primary + :expand: + + Archive source code + + .. grid-item-card:: Browse + :link: landing-browse + :link-type: ref + + .. image:: images/card_browse_undraw_file_searching.svg + :width: 49% + :align: center + :class: sd-mb-2 + + Our vast archive can be searched and accessed in multiple ways. Use it to reference unambiguously any part of a source code to your peers: fragment of code, directory, release, etc. + + .. button-ref:: landing-browse + :ref-type: ref + :color: primary + :expand: + + Learn how to search the archive + + .. grid-item-card:: Outreach + :link: landing-outreach + :link-type: ref + + .. image:: images/card_outreach_undraw_engineering_team.svg + :width: 99% + :align: center + :class: sd-mt-3 sd-mb-2 + + Join our network of partners. Collaborate with the team or become an ambassador. Teach others how to use the archive. Get materials for your next events. + + .. button-link:: http://example.com + :color: primary + :expand: + + Tell the world about Software Heritage + + .. grid-item-card:: Interface + :link: landing-interface + :link-type: ref + + .. image:: images/card_interface_undraw_futuristic_interface.svg + :width: 49% + :align: center + :class: sd-mb-2 + + Develop or research using Software Heritage. Browse, access or import source code programmatically. + + .. button-ref:: landing-interface + :ref-type: ref + :color: primary + :expand: + + Use Software Heritage in your applications + + .. grid-item-card:: Contribute + :link: landing-contribute + :link-type: ref + + .. image:: images/card_contribute_undraw_dev_focus.svg + :width: 80% + :align: center + :class: sd-mt-2 sd-mb-5 + + Enhance our collection, preservation, and querying processes. + + .. button-ref:: landing-contribute + :ref-type: ref + :color: primary + :expand: + + Improve the universal archive of source code + + + + + + +.. toctree:: + :maxdepth: 2 + :caption: Welcome: + :titlesonly: + :hidden: + + Discover Software Heritage + Archive source code + Search, browse and reference + Tell the world + Use in your applications + Improve the universal archive .. toctree:: :maxdepth: 2 - :caption: Contents: + :caption: Misc: :titlesonly: :hidden: diff --git a/user/landing-basics.rst b/user/landing-basics.rst new file mode 100644 --- /dev/null +++ b/user/landing-basics.rst @@ -0,0 +1,43 @@ +.. _landing-basics: + +Basics +====== + +.. grid:: 1 2 2 2 + :padding: 0 + + .. grid-item:: + + Learn about our mission and our source code archive. Find out about how to + make your first steps with the archive. + + .. grid-item:: + + .. image:: images/card_basics_undraw_discoverable.svg + :align: right + +Why an universal software archive? +---------------------------------- + +- `A video to get to know Software + Heritage `__ +- `Our mission `__ +- `Our approach `__ +- `The content of the archive at a + glance `__ + +Software Heritage in practice +----------------------------- + +- `Take a guided tour of the archive key + features `__ +- `Overview of the main + features `__ +- `Access and reuse the source + code `__ +- `Good practices for archiving and referencing your + code `__ +- `Get a permanent identifier for your source + code `__ +- `General FAQ `__ +- `Glossary `__ \ No newline at end of file diff --git a/user/landing-browse.rst b/user/landing-browse.rst new file mode 100644 --- /dev/null +++ b/user/landing-browse.rst @@ -0,0 +1,31 @@ +.. _landing-browse: + +Browse +====== + +.. grid:: 1 2 2 2 + :padding: 0 + + .. grid-item:: + + Search and access the archive, or use it to reference unambiguously any + part of a source code. + + .. grid-item:: + + .. image:: images/card_browse_undraw_file_searching.svg + :width: 50% + :align: right + +- `Take the guided tour of the archive web + interface `__ +- `Good practices for archiving and referencing your + code `__ +- `Make your code identifiable : get a PID for your source + code `__ +- `Choosing what type of Software Heritage Identifier (SWHID) to + use `__ +- `Navigating through Software Heritage: behind the + scenes `__ + +Need help? Want to make a proposal? Ask the community using the `users mailing-list `__ \ No newline at end of file diff --git a/user/landing-contribute.rst b/user/landing-contribute.rst new file mode 100644 --- /dev/null +++ b/user/landing-contribute.rst @@ -0,0 +1,43 @@ +.. _landing-contribute: + +Contribute +========== + +.. grid:: 1 2 2 2 + :padding: 0 + + .. grid-item:: + + There are many ways to help Software Heritage. However small or large, + contributions are welcome and very much appreciated. + + .. grid-item:: + + .. image:: images/card_contribute_undraw_dev_focus.svg + :align: right + +- `Our + roadmap `__ +- `Developper + documentation `__. Where + you will find developer-oriented documentation to understand the SWH + environment. + + - `Quick + start `__ + +Contributing development skills: + +- `Software architecture + overview `__ +- `Developers + portal `__ +- `Development + mailing-list `__. Join + the community +- `Development FAQ `__ + +Contributing resources and infrastructure: + +- `Mirror + operations `__ diff --git a/user/landing-interface.rst b/user/landing-interface.rst new file mode 100644 --- /dev/null +++ b/user/landing-interface.rst @@ -0,0 +1,42 @@ +.. _landing-interface: + +Interface +========= + +.. grid:: 1 2 2 2 + :padding: 0 + + .. grid-item:: + + Interact with our source code archive from your applications or research projects. + + .. grid-item:: + + .. image:: images/card_outreach_undraw_engineering_team.svg + :align: right + +Browse API +---------- + +- `Terms of use for Software Heritage + API `__ +- `Web API `__. Access the + API overview or discover the full `endpoints + index `__ + +Data model and identifiers +-------------------------- + +- `Our data + model `__ +- `Software Heritage IDentifiers + (SWHID) `__ + specifications +- Compute a SWHID locally using + `swh identify `__ command-line tool. + +Deposit API +----------- + +- `Import source code + programmatically `__ \ No newline at end of file diff --git a/user/landing-outreach.rst b/user/landing-outreach.rst new file mode 100644 --- /dev/null +++ b/user/landing-outreach.rst @@ -0,0 +1,35 @@ + +.. _landing-outreach: + +Outreach +======== + +.. grid:: 1 2 2 2 + :padding: 0 + + .. grid-item:: + + Wherever you have a technical background or not, help us spread the word + about Software Heritage. Encourage developers to archive their source + code. Find researchers and practitioners interested in using an immense + collection of source code. + + .. grid-item:: + + .. image:: images/card_outreach_undraw_engineering_team.svg + :align: right + +Ambassador program +------------------ + +- `Become an ambassador `__ + +- `Ambassadors mailing list `__ +- `Outreach material (only available to ambassadors) `__ +- `Outreach material on a Git repository `__ + +Presentations +------------- + +- `Archive of presentation + slides `__ diff --git a/user/landing-preserve.rst b/user/landing-preserve.rst new file mode 100644 --- /dev/null +++ b/user/landing-preserve.rst @@ -0,0 +1,75 @@ +.. _landing-preserve: + +Preserve +======== + +.. grid:: 1 2 2 2 + :padding: 0 + + .. grid-item:: + + There are multiple ways to add or update source code in Software Heritage + archive. Some of them are automated: our tools crawl multiple software + development plateforms to archive as many open projects as possible. + Others require manual procedures. + + .. grid-item:: + + .. image:: images/card_preserve_undraw_moving.svg + :align: right + +Before anything… +---------------- + +- `Good practices for archiving and referencing your + code `__ + +Save a code repository +---------------------- + +- “Ready to go” options to save your code : + + - Seamlessly check if a repository that you are browsing is archived + and up to date using our `Software Heritage browser + extensions `__ + - `Submit a save request on the Software Heritage + interface `__ + +- Automate the archival: + + - `Trigger a GitHub action that saves the GitHub + repository `__ + - `Trigger archival of a repository automatically : Bitbucket + endpoint, GitHub endpoint, GitLab + endpoint `__ + +Save multiple projects at a time, save a forge +---------------------------------------------- + +Save a forge in 2 steps : + +1. `Create an account + `__ +2. `Submit a request of archival for to save a complete forge + `__ + +`Technical insight on the “Add forge now” process +`__ + +Save code used for science +-------------------------- + +Save a software using ELife, Ipol, HAL. Your content are directly pushed +into the archive by trusted partners using the deposit service of +Software Heritage: + +- `Deposit software using the HAL + portal `__ +- `Video tutorial on source code deposit using + Hal `__ + +Save legacy source code +----------------------- + +Recovering and curating landmark legacy source code : `how to save +legacy code `__ \ No newline at end of file