Skip to end of metadata
Go to start of metadata

Creating Section and Document Links

:doc:

Please do not include direct links to pages on docs.acumos.org. Once the Docs project branches for Athena, those direct links will point to "master" branch docs instead of Athena branch docs.

Please **do** use the :doc: directive.

The Docs project has the following structure:
documentation
- docs
-- AcumosContributor
-- AcumosUser
--- onclick-deploy
--- portal-admin
--- portal-user
-- architecture
-- docs-contributor-guide
-- release-notes
-- submodules
--- acumos-azure-client
---- docs
---- tutorial
----- index
---- ...
--- <linked directory for each component>

When the Docs project is built, each linked submodule and corresponding docs folder is pulled for compilation.

Example of how to link to another component's guide:
source: kubernetes-client/docs/deploy-in-private-k8s.rst


INCORRECT:
See the `Acumos Azure Client Developers Guide <https://docs.acumos.org/en/latest/submodules/acumos-azure-client/docs/developer-guide.html>`_ for more info.


CORRECT:

See the :doc:`Acumos Azure Client Developers Guide <../../submodules/acumos-azure-client/docs/developer-guide>` for more info.

Example of how to link to a component from the Platform Architecture Guide:
source: docs/architecture/platform-architecture.rst
The various clients used to onboard models call the APIs in the Onboarding service. See the :doc:`Onboading App <../../submodules/on-boarding/docs/index>` documentation for details.

Example of how to link to a Portal User Guide page from a component:
source: acumos-java-client/docs/developer-guide.rst and you want to link to the Java onboarding page in the Portal User Guide:
 

To onboard a Java model, please see the :doc:`web onboarding guide <../../../../AcumosUser/portal-user/portal/onboarding-java-guide>`.


http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role

:doc: Link to the specified document; the document name can be specified in absolute or relative fashion. For example, if the reference :doc:`parrot` occurs in the document sketches/index, then the link refers to sketches/parrot. If the reference is :doc:`/people` or :doc:`../people`, the link refers to people.If no explicit link text is given (like usual: :doc:`Monty Python members </people>`), the link caption will be the title of the given document.


:ref:

see the :ref:`sign-in` section below.


.. _sign-in:


Linking to a Section in the Same File

from the Platform Architecture Guide:

E3 - OA&M APIs
..............

The OA&M subsystem defines data formats supported by the various logging
and analytics support components described under
`Operations, Admin, and Maintenance (OAM)`_. These are primarily focused on
log formats that Acumos components will follow when saving log files that are
collected by the logging subsystem.

Automatic Section Numbering

Section numbering

If you want to have section numbers even in HTML output, give the toplevel toctree a numbered option. For example:

.. toctree::
   :numbered:

   foo
   bar

Numbering then starts at the heading of foo. Sub-toctrees are automatically numbered (don’t give the numbered flag to those).

Numbering up to a specific depth is also possible, by giving the depth as a numeric argument to numbered.


http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html

Sphinx Directives

http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html

Command Line Word Wrapping

Unix/Linux:  fold command

https://linux.die.net/man/1/fold

https://shapeshed.com/unix-fold/

https://www.computerhope.com/unix/ufold.htm

fold -s 

If no file is specified, fold reads from standard input.


aimeeu@aimeeu-7520:~/Dev/git/gerrit.acumos.org/1813-docs-publisher/documentation$ fold -s
From the **Publish Request** page, a Publisher is able to view requests to publish models to the Public Marketplace, view model details by clicking on a request, approve a request, and decline a request.
From the **Publish Request** page, a Publisher is able to view requests to
publish models to the Public Marketplace, view model details by clicking on a
request, approve a request, and decline a request.


Sphinx RST

http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html



  • No labels