diff options
Diffstat (limited to 'files/pt-pt/mdn/contribute/howto/write_an_api_reference')
| -rw-r--r-- | files/pt-pt/mdn/contribute/howto/write_an_api_reference/sidebars/index.html | 110 |
1 files changed, 110 insertions, 0 deletions
diff --git a/files/pt-pt/mdn/contribute/howto/write_an_api_reference/sidebars/index.html b/files/pt-pt/mdn/contribute/howto/write_an_api_reference/sidebars/index.html new file mode 100644 index 0000000000..63a34dd7fe --- /dev/null +++ b/files/pt-pt/mdn/contribute/howto/write_an_api_reference/sidebars/index.html @@ -0,0 +1,110 @@ +--- +title: Barras laterais de referência da API +slug: MDN/Contribute/Howto/Write_an_API_reference/Sidebars +tags: + - API + - Guía + - Referencia + - barras laterais + - groupdata + - onboarding +translation_of: MDN/Structures/API_references/API_reference_sidebars +original_slug: MDN/Structures/API_references/Barras_laterais_de_referencia_da_API +--- +<div>{{MDNSidebar}}</div><p class="summary">Pode incluir uma barra lateral personalizada nas páginas de referência da API para exibir as hiperligações para as 'Interfaces' relacionadas, tutoriais, e outros recursos relevantes, apenas para essa API. Este artigo explica como.</p> + +<h2 id="O_que_precisa_de_fazer">O que precisa de fazer?</h2> + +<p>You need to take the following three steps to create your API sidebar:</p> + +<ol> + <li>Create your API reference pages.</li> + <li>Add an entry for your particular API into the <a href="https://github.com/mdn/kumascript">KumaScript repo</a>'s GroupData.json data file.</li> + <li>Use the \{{APIRef}} macro to insert the sidebar into each page you want to display it on.</li> +</ol> + +<p>Let's run through each of these steps in turn. The example we'll refer to in this article is the <a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a>.</p> + +<h3 id="Criar_páginas_de_referência_da_sua_API">Criar páginas de referência da sua API</h3> + +<p>Before you can add sidebars to your pages, you'll need to create the pages themselves (see our <a href="/en-US/docs/MDN/Contribute/Structures/API_references/What_does_an_API_reference_need">What does an API reference need?</a> guide for more guidance).</p> + +<h3 id="Adicionar_uma_entrada_para_GroupData.json">Adicionar uma entrada para GroupData.json</h3> + +<p>The <a href="https://github.com/mdn/kumascript/blob/master/macros/GroupData.json">GroupData.json</a> file holds all the data relating to what links should appear in API reference sidebars. When invoked, the \{{APIRef}} macro takes an API name given to it as a parameter, looks up that name in GroupData.json, builds a sidebar as appropriate, and inserts it in the page.</p> + +<p>To add an entry to GroupData.json, you need to:</p> + +<ol> + <li>Make sure you have a <a href="https://github.com/">GitHub</a> account.</li> + <li>Fork the KumaScript repo, create a new branch to contain your changes, and clone the repo locally.</li> + <li>Checkout your new branch before starting work, and make sure you push changes to it after finishing.</li> + <li>Create a pull request so that the MDN team can review your work, and ask for changes if necessary.</li> +</ol> + +<p>If you need help with using GitHub, a more detailed guide can be found at our <a href="/en-US/docs/MDN/Contribute/Structures/Compatibility_tables#The_new_way_The_browser_compat_data_repo_and_dynamic_tables">compatibility tables guide</a>.</p> + +<p>The <a href="https://github.com/mdn/kumascript/blob/master/macros/GroupData.json">GroupData.json</a> file can be found inside the macros directory of the KumaScript repo. Looking at it, you'll see a giant JSON structure, with each API having its own member. The name is the API name, and the value is an object containing several submembers defining the sidebar links to be created.</p> + +<p>For example, look at the <a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a> page on MDN. The corresponding entry in GroupData.json looks like this:</p> + +<pre class="brush: json notranslate">"Fetch API": { + "overview": [ "Fetch API"], + "interfaces": [ "Body", + "Headers", + "Request", + "Response", + "FetchController", + "FetchObserver", + "FetchSignal", + "ObserverCallback" ], + "methods": [ "WindowOrWorkerGlobalScope.fetch()" ], + "properties": [], + "events": [] +},</pre> + +<p>As you can see, we've used "Fetch API" for the name, and inside the object value we include a number of submembers.</p> + +<h4 id="Submembers_to_include_inside_a_GroupData_entry">Submembers to include inside a GroupData entry</h4> + +<p>This section lists all the submembers you could include in a GroupData entry.</p> + +<p>Note that Most of the values included inside the listed submembers equate to both the link text, and slugs appended to the end of the main API index page — https://developer.mozilla.org/<em><language-code></em>/docs/Web/API — to create the final URL for the displayed link. So for example, "Body" will result in a link being created like so in the <em>en-US</em> locale:</p> + +<pre class="brush: html notranslate"><li><a href="https://developer.mozilla.org/en-US/docs/Web/API">Body</a></li></pre> + +<p>There are a few exceptions. For example the "guides" submember contains one or more sets of link information (title and slug) that defines links to associated guides/tutorials. In this case the slugs are appended to the end of the MDN docs root — https://developer.mozilla.org/<em><language-code></em>/docs — allowing an article anywhere on MDN to be included.</p> + +<p>Here are the available members. In each case, an example is included that assumes that the local is <em>en-US</em>.</p> + +<ol> + <li> + <p>"overview" — the value is an array, inside of which you include the slug of the API overview page, if there is one. "Fetch API" results in a link being made to <a href="/en-US/docs/Web/API/Fetch_API">https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API</a>.</p> + </li> + <li> + <p>"interfaces" — the value is an array in which you should list all of the interfaces that form part of that API. "Body" results in a link being made to <a href="/en-US/docs/Web/API/Body">https://developer.mozilla.org/en-US/docs/Web/API/Body</a>.</p> + </li> + <li> + <p>"methods" — the value is an array that should contain all of the methods associated with the API. This can include methods that are members of interfaces defined in the API spec, and methods the API defines on other interfaces. If there are a huge number of methods, you might want to consider only listing the most popular ones, or putting them first in the list. "WindowOrWorkerGlobalScope.fetch()" results in a link being made to <a href="/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch">https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch</a>.</p> + </li> + <li> + <p>"properties" — the value is an array that should contain all of the properties associated with the API. This can include properties that are members of interfaces defined in the API spec, and properties the API defines on other interfaces. If there are a huge number of properties, you might want to consider only listing the most popular ones, or putting them first in the list. "Headers.append" results in a link being made to <a href="/en-US/docs/Web/API/Headers/append">https://developer.mozilla.org/en-US/docs/Web/API/Headers/append</a>.</p> + </li> + <li> + <p>"events" — the value is an array that should contain all of the events associated with the API, defined in the API spec, or elsewhere. If there are a huge number of events, you might want to consider only listing the most popular ones, or putting them first in the list. "animationstart" results in a link being made to <a href="/en-US/docs/Web/Events/animationstart">https://developer.mozilla.org/en-US/docs/Web/Events/animationstart</a>.</p> + </li> + <li> + <p>"guides" — the value is an array containing one or more objects that define links to guides explain how to use the API. Each object contains two submembers — "url", which contains the partial URL pointing to the guide article, and "title", which defines the link test for the link. As an example, the following object:</p> + + <pre class="brush: json notranslate">{ "url": "/docs/Web/API/Detecting_device_orientation", +"title": "Detecting device orientation" }</pre> + + <p>Creates a link with the title "Detecting device orientation", which points to <a href="/en-US/docs/Web/API/Detecting_device_orientation">https://developer.mozilla.org/en-US/docs/Web/API/Detecting_device_orientation</a>.</p> + </li> +</ol> + +<h3 id="Inserir_a_barra_lateral_nas_suas_páginas">Inserir a barra lateral nas suas páginas</h3> + +<p>Once you've added an entry for your API into GroupData.json, submitted it as a pull request and had the change accepted into the main repo, you can include it in your API reference pages using the \{{APIRef}} macro, which takes the name you used for your API in GroupData as a parameter. As an example, the <a href="/en-US/docs/Web/API/WebVR_API">WebVR API</a>'s sidebar is included in its pages with the following:</p> + +<p>\{{APIRef("WebVR API")}}</p> |