{"id":15992315,"url":"https://github.com/sbesson/contributing","last_synced_at":"2025-03-17T10:45:15.892Z","repository":{"id":145306852,"uuid":"223495741","full_name":"sbesson/contributing","owner":"sbesson","description":null,"archived":false,"fork":false,"pushed_at":"2019-11-22T22:22:00.000Z","size":67292,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-23T20:22:57.738Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sbesson.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-22T22:19:05.000Z","updated_at":"2019-11-22T22:23:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"4d63a46a-afec-48e3-bbb3-9ae0a0a1c1c6","html_url":"https://github.com/sbesson/contributing","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbesson%2Fcontributing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbesson%2Fcontributing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbesson%2Fcontributing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbesson%2Fcontributing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sbesson","download_url":"https://codeload.github.com/sbesson/contributing/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244020883,"owners_count":20385034,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-08T06:20:56.225Z","updated_at":"2025-03-17T10:45:15.869Z","avatar_url":"https://github.com/sbesson.png","language":"Python","readme":"Documentation files to be linked under the ``docs/sphinx`` directory of\nhttps://github.com/openmicroscopy/openmicroscopy.\n\n.. image:: https://travis-ci.org/openmicroscopy/ome-documentation.png\n   :target: https://travis-ci.org/openmicroscopy/ome-documentation\n\n***************************\nGetting Started With Sphinx\n***************************\n\nInitial setup\n=============\n\nSphinx\n------\n\nSphinx depends on the ``sphinx-build`` Python script. As such, it can be\ninstalled on any system with a working Python installation and PIP. On\nWindows, make sure that the ``Scripts`` directory under the Python\ninstallation directory (e.g. ``C:\\Python26\\Scripts``) is configured in your\nPATH. On OS X/Linux, ``sphinx-build`` has to be accessible from the command\nline.\n\nThe Sphinx documentation system can be obtained by issuing::\n\n    pip install Sphinx\n\nMost Linux distributions will also provide it in a python-sphinx package\n(or similar).\n\nAnt\n---\nYou will also need ant for building the documentation. This can be installed\non Mac OSX by using homebrew::\n\n    brew install ant\n\n\nStructure and organization\n==========================\n\nThe OME documentation is organized into multiple folders:\n\n* the OMERO documentation is under the ``omero`` folder,\n* the OME Contributing Developer documentation is under the ``contributing`` \n  folder,\n* the shared configuration and themes are under the ``common`` folder.\n\nThe structure of each documentation folder follows the Sphinx system\nguidelines. A quick overview:\n \n* source \\*.rst files with reST markup live in the root of the folder and\n  under subfolders,\n* images/screenshots are placed under ``images``,\n* downloadable files are placed under ``downloads``,\n* compiled output is placed in ``_build``,\n* compiled visual themes are automatically placed in ``_static``,\n* Sphinx configuration is held in ``conf.py``,\n* goals for ``make`` and ``make.bat`` are held in ``Makefile``.\n \nA reference of reStructuredText (reST) is available at\n`https://thomas-cokelaer.info \u003chttps://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html\u003e`_.\nIt is recommended to familiarise oneself with the syntax outlined there.\n\nA tutorial covering Sphinx, which enhances working with reST documents, can be\nfound at `http://sphinx.pocoo.org \u003chttp://sphinx.pocoo.org/tutorial.html\u003e`_.\n\nBuilding the documentation\n==========================\n\nThe documentation may be built with ``make`` or ``ant``.  Note that ``ant``\nrequires ``ant-contrib`` to be on the classpath.\n\nBasic build commands\n--------------------\n\nTo build a set of documentation, first move to the documentation folder. To\nbuild the OMERO documentation::\n\n    cd omero/\n\nor to build the Contributing Developer documentation::\n\n   cd contributing/\n\nTo clean the build directory of any previous builds, use one of::\n    \n    make clean\n    ant clean\n    \nTo build the documentation locally in the form of HTML pages, use one of::\n    \n    make html\n    ant html\n    \nTo check the links (internal and external) of the documentation, use one of::\n    \n    make linkcheck\n    ant linkcheck\n    \nBy default, ``make`` will build the documentation locally in the form of HTML pages.\n\n\nTop-level build command\n-----------------------\n\nThe top-level directory Makefile also defines targets for building both the\nOMERO and Contributing sets of documentation at once.\n\nTo clean the build directories of any previous builds, use one of::\n\n    make clean\n    ant clean\n\nTo build the sets of documentation locally in the form of HTML pages, use one of::\n\n    make html\n    ant html\n\nBy default, running ``make`` will build the documentation locally in the form of HTML pages.\n\nMakefile options\n----------------\n\nAdditional options for sphinx-build can be passed using the ``SPHINXOPTS``\nvariable. The ``-W`` option turns all warnings into errors::\n\n    SPHINXOPTS=-W make clean html\n    SPHINXOPTS=-W ant clean html\n\nRelease number\n--------------\n\nThe release number of the OMERO documentation is `UNKNOWN` by default.\nTo modify this value set the environment variable ``OMERO_RELEASE`` e.g.::\n\n    cd omero \u0026\u0026 OMERO_RELEASE=5.4.0 make clean html\n    cd omero \u0026\u0026 OMERO_RELEASE=5.4.0 ant clean html\n\nThis variable needs to be set to build all the version-dependent content\nused in the system administrator documentation correctly.\n\nThe Contributing Developer documentation has the release version removed as\nthe intention is to update these files as and when necessary, so that they\nalways reflect our current practices.\n\nZip bundles\n-----------\n\nTo build the documentation as a zipped bundle, use::\n\n    ant zip\n\nBy default, running ``ant`` will build as a zipped bundle.\n\nFrom the top level directory::\n\n    OMERO_RELEASE=5.4.0 ant zip -Domero.release=\"5.4.0\"\n\nwill generate the HTML documentation for OMERO and Contributing and bundle\njust the OMERO documentation into an OMERO.doc-5.4.0.zip under omero/_build.\n\nFrom omero directory::\n\n    OMERO_RELEASE=5.4.0 ant zip -Domero.release=\"5.4.0\"\n\nwill generate the HTML documentation for OMERO and create an\nOMERO.doc-5.4.0.zip under omero/_build.\n\nFrom the contributing directory::\n\n    ant zip -Domero.release=\"5.4.0\"\n\nwill generate the HTML documentation for Contributing and create a\nCONTRIBUTING.doc-5.4.0.zip under contributing/_build.\n\nAuto-generated content\n----------------------\n\nSome parts of the OMERO documentation are auto-generated from the OMERO\ndeliverables (e.g. templates, command-line output...). This auto-generation is\nusually done via Continuous Integration builds. To generate these components\nmanually, download the OMERO.server and run the auto-generation script as::\n\n      WORSKSPACE=/path/to/OMERO/deliverables ./omero/autogen_docs\n\n****************\nConventions Used\n****************\n\nPart of the conventions used here is based on work by\n`Benoît Bryon \u003chttps://github.com/benoitbryon/documentation-style-guide-sphinx\u003e`_.\n\nFile names\n==========\n\nreST source file names should carry the ``rst`` suffix and use lowercase\nalphanumeric characters and the ``-`` (minus) symbol.\n\nIndentation\n===========\n\nMost reST directives do not need indentation, unless contents or options have\nto be supplied. For consistency, please use 4 space indentation whenever\nneeded. Do not use indentation for the start of directives (start them at the\nedge of the new line). Any content under a reST directive has to be indented\nthe same way as the options.\n\nExample::\n    \n    .. toctree::\n        :maxdepth: 2\n        \n        Some content here...\n    \nLine wrapping\n=============\n\nreST source files should use 78 lines for wrapping text. Please consult the\nmanual of your favourite text editor to see how to switch on text wrapping.\n\nBlank lines\n===========\n\nTwo new lines should be put before top-lined, top-level section names, i.e.\nbefore H1 and H2. One new line in any other case.\n\nExample::\n    \n    ###############\n    Part title (H1)\n    ###############\n    \n    Introduction text.\n    (blank)\n    (blank)\n    ******************\n    Chapter title (H2)\n    ******************\n    \nTitle headings\n==============\n\nEvery reST source file should begin with an H2 (level two) title. H1 titles\nare reserved for the index files (``index.rst``).\n\nThe following symbols should be used to create headings:\n \n* ``#`` with top line for parts\n* ``*`` with top line for chapters\n* ``=`` for sections\n* ``-`` for subsections\n* ``^`` for subsubsections\n* ``\"`` for paragraphs\n \nExample::\n    \n    ###############\n    Part Title (H1)\n    ###############\n    \n    H1 only in indexes.\n    \n    \n    ******************\n    Chapter Title (H2)\n    ******************\n    \n    Sample file content.\n    \n    \n    ********************\n    Another chapter (H2)\n    ********************\n    \n    Section title (H3)\n    ==================\n    \n    Subsection title (H4)\n    ---------------------\n    \n    Subsubsection title (H5)\n    ^^^^^^^^^^^^^^^^^^^^^^^^\n    \n    Paragraph title (H6)\n    \"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n    \n    And some text.\n    \nPage labels and references\n==========================\n\nEvery page can be uniquely referenced using the sphinx doc directive. Like\nother directives, you can use the absolute file path, i.e. relative to the\ntop-level directory:\n``:doc: `/path/name-of-the-page``` or ``:doc: `link to my page \u003c/path/name-of-the-page\u003e```.\n\nOnly when a good reason exists, a document can also start with a label::\n    \n    .. _page-label:\n    \n    \n    Title Of The Page\n    =================\n\nUse of labels to refer to whole files is discouraged. References to labels\nabove tables and images are encouraged. The ``:ref:`` Sphinx role is advised\nover standard reST links, as it works across files and reference names are\nautomatically generated (e.g. from caption of an image).\n\nImages vs. figures\n==================\n\nreST allows for two types of image embedding: using the ``image`` and\n``figure`` directive. It is recommended to use the latter, as legends and\ncaptions can be added easier.\n\nAll images referenced in a reST document shall be placed in an ``images``\nfolder in the top-level directory of the documentation.\n\nPlease do not use relative (``../../../images/foo.jpg``) paths to refer to\nimages. Sphinx does a good job at creating paths, so one can use\n``/images/foo.jpg``\n\nTables\n======\n\nPlease do not use tables for collections of links and figures, and leave them\nsolely for use as actual tables. While it can be used in HTML to shoehorn\ncontent into boxes, it does not work too well for other output.\n\nBig tables (typically wider than 50 characters) should be managed as external\nfiles using the comma-separated values (CSV) format. These tables can then be\nincluded in the documentation with the ``csv-table`` directive. If tables are\nsaved using the tab-separated values (TSV) format use the ``delim`` option to\nset the table delimiter to `tab` e.g.::\n\n    .. csv-table::\n        :widths: 20 80\n        :header-rows: 1\n        :file: searchfieldnames.tsv\n        :delim: tab\n\n\nSubstitutions, aliases and hyperlinks\n=====================================\n\nreST allows for using substitutions in cases where a piece of markup is used\nmore than once, e.g.::\n    \n    Please visit Python.org_\n    \n    ...\n    \n    .. _Python.org: https://www.python.org\n    \nIf a hyperlink appears only once, please use anonymous, \"one-off\" hyperlinks\n(two underscores)::\n    \n    `RFC 2396 \u003chttps://www.rfc-editor.org/rfc/rfc2396.txt\u003e`__ and `RFC\n    2732 \u003chttps://www.rfc-editor.org/rfc/rfc2732.txt\u003e`__ together\n    define the syntax of URIs.\n    \nFinally, please avoid using ``here`` as the hyperlink name, as in::\n    \n    (...) go `here \u003chttp://www.google.com\u003e`_.\n    \n    \nCommon markups\n==============\n\nPlease try to follow the rules outlined in\n`Inline Markup \u003chttp://sphinx-doc.org/markup/inline.html\u003e`_. This allows for\nimproving the semantics of the document elements.\n\n* Notes should be formatted using the note directive: ``.. note::``\n* Definition lists can be created and cross-referenced using the glossary\n  directive: ``.. glossary::``. Each definition can be referenced anywhere in\n  the documentation using the ``:term:`` role and an entry will be added for\n  every term in the generated index.\n* References to external documentation can be formatted using:\n  ``.. seealso::``\n* Menu selections should be marked using the appropriate role:\n  ``:menuselection: `Start --\u003e Programs```\n* Environment variables should be formatted using the ``:envvar:`` role.\n  This  role will add an entry for the variable in the generated index.\n* CLI Commands can be formatted using the following role:\n  ``:omerocmd: `admin start```\n  This role will render as ``omero admin start`` and add an entry for\n  the command in the generated index.\n* Other commands should be formatted using the literal markup:\n  ``:literal: `command``` or double back quoted markup\n* Configuration properties for OMERO.server and OMERO.web are marked using\n  the custom ``property`` directive and can be cross referenced e.g. using\n  ``:property: `omero.data.dir```\n* Other useful inline markups include: ``:option:`` and ``:guilabel:``\n* Do not use inline highlighting or other markups in headings or subheadings\n\nGlobal substitutions\n====================\n\nSome substitutions have been implemented using ``rst_epilog`` in ``conf.py``.\nThey can be used in all pages of the documentation.\n\nHyperlinks\n----------\n\nThe table below lists targets for common hyperlinks.\n\n=========================== ==============================================\nTarget name                 Link\n=========================== ==============================================\nPython                      https://www.python.org\nMatplotlib                  https://matplotlib.org/\nPillow                      https://pillow.readthedocs.org\nHibernate                   http://www.hibernate.org\nZeroC                       https://zeroc.com\nIce                         https://zeroc.com\nJenkins                     https://jenkins.io/\nroadmap                     https://trac.openmicroscopy.org/ome/roadmap\nOpen Microscopy Environment https://www.openmicroscopy.org\nGlencoe Software, Inc.      https://www.glencoesoftware.com/\nPyPI                        https://pypi.org\n=========================== ==============================================\n\nAbbreviations\n-------------\n\nThe table below lists substitutions for common abbreviations. These\nsubstitutions use the ``:abbr:`` Sphinx role meaning they are shown as\ntool-tip in HTML.\n\n======= ============= ======================\nName    Abbreviation  Explanation\n======= ============= ======================\n\\|SSH\\| SSH           Secure Shell\n\\|VM\\|  VM            Virtual Machine\n\\|OS\\|  OS            Operating System\n\\|SSL\\| SSL           Secure Socket Layer\n\\|HDD\\| HDD           Hard Disk Drive\n\\|CLI\\| CLI           Command Line Interface\n======= ============= ======================\n\nOMERO page references\n---------------------\n\nThe table below lists substitutions that can be used to create references to \nsections of the OMERO documentation.\n\n==================  ===========================\nName                Path\n==================  ===========================\n\\|OmeroPy\\|         developers/Python\n\\|OmeroCpp\\|        developers/Cpp\n\\|OmeroJava\\|       developers/Java\n\\|OmeroMatlab\\|     developers/Matlab\n\\|OmeroApi\\|        developers/Modules/Api\n\\|OmeroWeb\\|        developers/Web\n\\|OmeroClients\\|    developers/GettingStarted\n\\|OmeroGrid\\|       sysadmins/grid\n\\|OmeroSessions\\|   developers/Server/Sessions\n\\|OmeroModel\\|      developers/Model\n\\|ExtendingOmero\\|  developers/ExtendingOmero\n\\|BlitzGateway\\|    developers/Python\n==================  ===========================\n\nFor the most up-to-date list, please consult ``conf.py`` (section\n``rst_epilog``).\n\nCommon URLs\n===========\n\nSome URLs are widely used across the OME documentation. Using the Sphinx\n``extlinks`` extension, a dictionary of aliases to base URLs has been defined\nfor the following:\n \n* image.sc forum: ``:imagesc: `tag \u003ctag\u003e```\n* Trac tickets: ``:ticket: `3442```, displayed as ``\u003ca\u003e#3442\u003c/a\u003e``\n* Snapshots: ``:snapshot: `omero/myzip.zip```\n* Website pages: ``:omero: `OMERO \u003c\u003e```\n* Downloads: ``:downloads: `OMERO downloads \u003c\u003e```\n\nFor the most up-to-date list, please consult ``conf.py`` (section\n``extlinks``). Note that there are separate ``conf.py`` files for each set of\ndocumentation, as well as a shared one under ``common/``.\n\nSource code links\n=================\n\nLinks to the OMERO source code hosted on Github can be created using the\n``source`` alias for single files, e.g. ``:source: `etc/grid/default.xml``` or\nthe ``sourcedir`` alias for directories, e.g. ``:sourcedir: `etc```.\n\nBy default, these links will point at the code under the ``develop`` branch or\nhttps://github.com/openmicroscopy/openmicroscopy. To specify a specific fork\nand/or  branch, set the SOURCE_USER and SOURCE_BRANCH environment variables,\ne.g.::\n\n    SOURCE_USER=sbesson SOURCE_BRANCH=my_branch make clean html\n    SOURCE_USER=sbesson SOURCE_BRANCH=my_branch ant clean html\n\nJenkins links\n=============\n\nLinks to the continuous integration server can be created using the \n``jenkins`` alias for the main server, e.g. ``:jenkins: `Jenkins server \u003c\u003e```,\nthe ``jenkinsjob`` alias for a given job, e.g. ``:jenkinsjob: `OMERO-4.4``` or\nthe ``jenkinsview`` alias for a given view, e.g. ``:jenkinsview: `4.4```.\n\nMailing-list links\n==================\n\nLinks to the OME mailing lists can be created using the ``mailinglist`` alias,\ne.g. ``:mailinglist:`ome-users/```. To point at specific discussion threads,\ntwo aliases have been defined ``ome-users`` and ``ome-devel``, e.g.\n``:ome-users:`ome-users thread \u003c2009-June/001839.html\u003e```.\n\nInclusion of content\n====================\n\nWhen a specific type of content (e.g. code snippet) repeats itself among many\npages, it is advised to store it in a separate file without the default\n``.txt`` extension. This file can then be later included using the\n``literalinclude`` directive.\n\n*******************\nWriting Conventions\n*******************\n\n* Do not use contractions (can't, isn't, I'll, etc.) or '\u0026' in the\n  documentation.\n* All H1 and H2 level headings should have a capital letter at the start of\n  each word.\n* All sub-headings (H3 +) should begin with a capital letter for the first\n  word and\n  continue in lowercase, except where they refer to terms which are\n  abbreviated in the text e.g. Virtual Machine.\n* Use the full product name, e.g. OMERO.insight instead of Insight.\n* Avoid using resp. in brackets to refer to alternative file names etc. Just\n  use 'or'.\n* Use full words rather than symbols in headings if possible.\n* When giving instructions, address the user as 'you' and try to maintain a\n  professional\n  attitude - i.e. no random asides about making coffee or smilies!\n* Bullet point lists should begin with a capital letter and end with a full\n  stop if each point is a complete sentence, or more than one sentence. If\n  not, no punctuation is necessary\n  (see https://en.oxforddictionaries.com/punctuation/bullet-points).\n* Note that if you are giving an example link which is phrased like a\n  hyperlink but not formatted as one because it does not actually exist, you\n  need to prepend it with a '\\\\' to escape the\n  link and stop the link-checker from reporting it as broken (e.g.\n  ``\\http://your_host/webclient/login/``), unless you use the literal mark-up.\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsbesson%2Fcontributing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsbesson%2Fcontributing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsbesson%2Fcontributing/lists"}