diff --git a/docs/developer-setup.rst b/docs/developer-setup.rst --- a/docs/developer-setup.rst +++ b/docs/developer-setup.rst @@ -60,6 +60,7 @@ sudo apt update sudo apt install nodejs +.. _checkout-source-code: Checkout the source code ------------------------ diff --git a/docs/faq/index.rst b/docs/faq/index.rst --- a/docs/faq/index.rst +++ b/docs/faq/index.rst @@ -11,8 +11,8 @@ What are the Skills required to be a code contributor? ------------------------------------------------------ -It depends on what area you want to work on. `Internships -`__ postings list specific skills +It depends on what area you want to work on. The `Internships postings ` +list specific skills required. Generally, only Python and basic Git knowledge are required. Feel free to contact us on one of the `development channels `__ for details. @@ -20,9 +20,8 @@ What are the minimum system requirements (hardware/software) to run SWH locally? -------------------------------------------------------------------------------- -Python3.7 or newer is required. See the `developer setup documentation -`__ for -more details. +Python3.7 or newer is required. See the :ref:`developer setup documentation +` for more details. .. _faq_getting_started: @@ -33,8 +32,8 @@ What are the must read docs before I start contributing? -------------------------------------------------------- -We recommend you read the top links listed at from the `documentation home page -`__ in order: getting started, +We recommend you read the top links listed at from the :ref:`documentation home page +` in order: getting started, contributing, and architecture, as well as the data model. Where can I see the getting started guide for developers? @@ -54,12 +53,12 @@ --------------------------------------------------------------------------------- Unfortunately, not at the moment. But you can look at the `Internship list -`__ to look for something matching +`_ to look for something matching this skill, and this may allow you to find topics to search for in the `bug tracking -system `__. +system`_. -Either way, feel free to `contact our developers -`__, we would love to work with +Either way, feel free to contact our developers through any of the +`development channels`_, we would love to work with you. Where should I ask for technical help? @@ -67,8 +66,8 @@ You can choose one of the following: -* `development channels `__ -* `contact form for any enquiries `__ +* `development channels`_ +* `contact form` for any enquiries .. _faq_run_swh: @@ -78,18 +77,16 @@ I have SWH stack running in my local. How do I get some initial data to play around? ------------------------------------------------------------------------------------ -You can setup a job on your local machine, for this you can `schedule a listing task -`__ +You can setup a job on your local machine, for this you can +:ref:`schedule a listing task ` for example. Doing so on small forge, will allow you to load some repositories. -Or you can also trigger directly `loading from the cli -`__. +Or you can also trigger directly :ref:`loading from the cli `. I have a SWH stack running in local, How do I setup a lister/loader job? ------------------------------------------------------------------------ -See the `"Managing tasks" chapter -`__ +See the :ref:`"Managing tasks" chapter ` in the Docker environment documentation. How can I create a user in my local instance? @@ -113,10 +110,9 @@ Is there a way to connect to SWH archived (production) database from my local machine? -------------------------------------------------------------------------------------- -We provide the archive as a dataset on public clouds, see the `swh-dataset -documentation `__. We can -also provide read access to one of the main databases on request `contact -us `__. +We provide the archive as a dataset on public clouds, see the :ref:`swh-dataset +documentation `. We can +also provide read access to one of the main databases on request, `contact us`_. .. _faq_error_bugs: @@ -126,10 +122,10 @@ I found a bug/improvement in the system, where should I report it? ------------------------------------------------------------------ -Please report it on our `bug tracking system `__. +Please report it on our `bug tracking system`_. First create an account, then create a bug report using the "Create task" button. You should get some feedback within a week (at least someone triaging your issue). If not, -`get in touch with us `__ to +`get in touch with us `_ to make sure we did not miss it. .. _faq_legal: @@ -157,9 +153,8 @@ -------------------------------------------------------------------------------------------- You are welcome to drop us a message at one of the `development -channels `__, we will pick it up -and fix it so you don't have to follow the whole `code review -process `__. +channels`_, we will pick it up +and fix it so you don't have to follow the whole :ref:`code review process `. What tests I should run before committing the code? --------------------------------------------------- @@ -171,15 +166,15 @@ I am getting errors while trying to commit. What is going wrong? ---------------------------------------------------------------- -Ensure you followed the proper guide to `setup your -environment `__ +Ensure you followed the proper guide to :ref:`setup your +environment ` and try again. If the error persists, you are welcome to drop us a message at one of the -`development channels `__ +`development channels`_ Is there a format/guideline for writing commit messages? -------------------------------------------------------- -See the `Git style guide `__ +See the :ref:`git-style-guide` Is there some recommended git branching strategy? ------------------------------------------------- @@ -205,12 +200,12 @@ How do I generate API usage credentials? ---------------------------------------- -See the `Authentication guide `__. +See the :ref:`Authentication guide `. Is there a page where I can see all the API endpoints? ------------------------------------------------------ -See the `API endpoint listing page `__. +See the `API endpoint listing page `_. What are the usage limits for SWH APIs? --------------------------------------- @@ -220,8 +215,7 @@ * 120 for anonymous users * 1200 for authenticated users -It's described in the `rate limit documentation page -`__. +It's described in the `rate limit documentation page `_. .. It's temporarily here but it should be moved into its own sphinx instance at some point in the future. @@ -250,3 +244,11 @@ internal state migration (dbs) often enters the release cycle and due to the data volume, that may need human intervention. + +.. _API: https://archive.softwareheritage.org/api/1/ +.. _API-rate-limit: https://archive.softwareheritage.org/api/#rate-limiting +.. _bug tracking system: https://forge.softwareheritage.org/ +.. _contact form: https://www.softwareheritage.org/contact/ +.. _contact us: https://www.softwareheritage.org/contact/ +.. _development channels: https://www.softwareheritage.org/community/developers/ +.. _internships: https://wiki.softwareheritage.org/wiki/Internships diff --git a/docs/index.rst b/docs/index.rst --- a/docs/index.rst +++ b/docs/index.rst @@ -1,4 +1,4 @@ - +.. _swh-docs: Software Heritage - Development Documentation =============================================