Editing the OME documentation ============================= This guide assumes you are already familiar with :doc:`using-git` and GitHub and only covers where to find the sources, builds etc. you will need to edit and review any given content. Further information on the CI builds is available on the :doc:`ci-docs` page. Some of the live web documentation also features ‘Show on GitHub’ and ‘Edit on GitHub’ links in the lefthand menu which will take you directly to the source file and allow you to edit within the GH interface and then open a PR (you should never use this functionality to edit autogenerated pages, see below for details of these). Overview -------- This page covers technical documentation which is written in ``.rst`` files and generated into html using Sphinx. There are sets for each aspect of the project, plus this set of ‘contributing developer’ documentation aimed at giving an overview of the OME process and workflows across products that might be of interest to external people, and the OME internal docs for internal-only private workflows and processes. Some of the content for these is either autogenerated or copied from external sources as described below. Formatting and style guidance can be found in the `README `_ for the ome-documentation repo, along with instructions for getting set up with Sphinx. The jekyll websites hosted by OME, which include the Help workflow guides, are covered on :doc:`jekyll`. What goes where? ---------------- The decision trees below try to give an insight into the thought process behind choosing what information to host where. .. figure:: /images/project-decision-tree.png :align: center :alt: Project-wide information can be hosted privately in the internal docs or gdocs or publicly in this documentation or on the blog for news-worthy items Project-wide information .. figure:: /images/product-decision-tree.png :align: center :alt: Product-specific information can be hosted in the sphinx docs or help site for instructions and how-tos while the website and/or blog can be used to highlight features and give an overview of functionality Product-specific information Bio-Formats documentation ------------------------- Hosted at ``_\{{version}} (plus latest redirect - :bf_doc:`docs.openmicroscopy.org/latest/bio-formats/ <>`) This documentation covers all aspects of Bio-Formats - using it with other tools, specific guidance for Bio-Formats developers, and supported formats. Related topics - OME file formats and the data model are covered in the OME Data Model and File Formats documentation. Builds ^^^^^^ See :doc:`ci-docs`. Source ^^^^^^ The Sphinx documentation is decoupled from the code repository, at ``_. Building locally ^^^^^^^^^^^^^^^^ The build uses Sphinx via ``Maven``. ``mvn`` will generate the webpages provided you have both Sphinx and Maven installed. To avoid running the linkchecker by default use ``mvn -DskipSphinxTests``. Building/reviewing PRs via the CI ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Once a PR is open, you can build it for review using the :mergecijob:`BIOFORMATS-linkcheck` job on the Jenkins CI. Staging documentation is no longer deployed at a URL but you can download it as a zip for review with the correct styling by going to the workspace folder in the job. Autogenerated content ^^^^^^^^^^^^^^^^^^^^^ The following parts of the documentation are autogenerated during the build: - Supported Formats table and format pages - generated from :bf_doc_source:`format-pages.txt ` - Dataset structure table - generated from the readers - Metadata support table - generated from the readers Generally, unless you are adding new file support, the format pages are the only ones you are likely to be editing. There is documentation on :bf_doc:`Adding format/reader documentation pages ` in the Bio-Formats developer section. Publishing ^^^^^^^^^^ The live webpages are updated as part of the release process. OME Contributing Developer documentation ---------------------------------------- Hosted at ``_ (always latest). This covers the OME team processes and workflows that may be of interest to external contributors or other open source teams - information about what tools we use and how, rather than internal-only workflows (like standup prep) or anything which needs to be kept private (these belong in the internal docs instead). Builds ^^^^^^ See :doc:`ci-docs`. Source ^^^^^^ The source files are at ``_. Building locally ^^^^^^^^^^^^^^^^ The build uses Sphinx. You can build locally using ``make clean html`` provided you have Sphinx. There is further information on getting these set up in the README. Building/reviewing PRs ^^^^^^^^^^^^^^^^^^^^^^ Once a PR is open, a build on Read the docs will be triggered. Staging documentation will be available at a given URL linked to the PR. See ``_ for more details. Publishing ^^^^^^^^^^ The live webpages are updated when a PR is merged. OME Data Model and File Formats documentation --------------------------------------------- Hosted at ``_\{{version}}/ (plus latest redirect - ``_). This covers the OME-TIFF format and the OME data model. Builds ^^^^^^ See :doc:`ci-docs`. Note that this documentation is built and hosted individually and as part of the OME Files documentation bundle. Source ^^^^^^ The documentation is in the ``/docs/sphinx/`` folder in the code repository at ``_. Building locally ^^^^^^^^^^^^^^^^ The build uses Sphinx via Maven. You can build locally using ``make clean html`` provided you have both installed. Building/reviewing PRs via the CI ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Once a PR is open, you can build it for review using the :mergecijob:`BIOFORMATS-build` job on the Jenkins CI. Staging documentation is no longer deployed at a URL but you can download it as a zip for review with the correct styling from the job page (see ‘Last Successful Artifacts’ at the top of the centre panel. Publishing ^^^^^^^^^^ The live webpages are updated as part of the release process. OME Internal documentation (private) ------------------------------------ For members of the OME team, this set of documentation is available at ``_ behind an ldap log-in. Builds ^^^^^^ :jenkinsjob:`OME-internal-merge-docs`. Source ^^^^^^ ``_ (private repository) Building locally ^^^^^^^^^^^^^^^^ The build uses Sphinx via ``ant``. You can build locally using ``make clean html`` provided you have both installed. Building/reviewing PRs via the CI ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Once a PR is open, you can build it using :jenkinsjob:`OME-internal-merge-docs` and then view the rendered text on the live webpages. Publishing ^^^^^^^^^^ Content is automatically published to the private URL each day or when the merge build is run. OMERO documentation ------------------- Hosted at ``_\{{version}}/ (plus latest redirect - :omero_doc:`https://docs.openmicroscopy.org/latest/omero/ <>`). This documentation includes developer and sysadmin documentation for OMERO, version history, client overviews and CLI usage documentation. Workflow-based user documentation belongs in the Help instead while features and other overview material aimed at scientists and other non-IT people may belong on the website (see :doc:`jekyll`). Builds ^^^^^^ See :doc:`ci-docs`. Source ^^^^^^ All the source files are in the ``/omero/`` folder at ``_. Building locally ^^^^^^^^^^^^^^^^ The build uses Sphinx via ``ant``. You can build locally using ``make clean html`` provided you have both installed. There is further information on getting these set up and on build targets in the `README`_. Building/reviewing PRs via the CI ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Once a PR is open, you can build it for review using the :mergecijob:`OMERO-docs` job on the Jenkins CI. Staging documentation are no longer deployed at a URL but you can download it as a zip for review with the correct styling from the top centre panel in the job, under ‘Last Successful Artifacts’. Autogenerated/inserted external content ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The OMERO documentation is the most complicated set, being the only repo where material is sourced from other repositories. Source repositories are: - ``_ (OMERO code repo) - ``_ (OMERO server with Web installation) - ``_ (OMERO.web separately from OMERO.server installation) Version history """"""""""""""" Content for :omero_doc:`OMERO version history ` should first be submitted as a PR against :omero_source:`history.rst` in the OMERO code repository. Best practice is to paste the content into the documentation page to test build it before opening the PR. Once the PR is merged, an autogenerated PR can be opened against the documentation repo to transfer the content. CLI output """""""""" The output of the following CLI commands will be used as configuration files in the documentation: - ``omero config parse`` - ``omero ldap setdn -h`` - ``omero db script`` - ``omero web config nginx`` - ``omero web config nginx-location`` See `autogen_docs `_ to check the name of the output files. Changes to the output should be submitted as a PR against the OMERO code repository. Installation walkthroughs """"""""""""""""""""""""" Installation walkthroughs for OMERO.server and OMERO.web are generated in separate repositories. When the installation instructions are modified e.g. a new dependency is added, a PR must be opened against one of the following repositories: - ``_ for server installation with OMERO.web - ``_ for OMERO.web installation not with an OMERO.server OMERO.server installation with OMERO.web: - The walkthroughs are generated using a bash script - Code snippets will be included in the documentation pages using `literalinclude` e.g. server-ubuntu-ice36.rst - The changes made against https://github.com/ome/omero-install will only be included in the documentation once they are merged and the autogen job has been run. When making changes that need to be visible in the documentation during review, you will need to: - Generate the walkthrough(s) - Open a doc PR - Copy the generated walkthrough(s) under `omero/sysadmins/unix/walkthrough `_ - Adjust if required the start/end of the `literalinclude` OMERO.web installation separately from OMERO.server: - The walkthroughs are generated using ansible. The `omeroweb-install README `_ file contains instructions on how to generate the walkthroughs - The generated walkthroughs are .rst files that are used as pages in the documentation. This workflow does not use `literalinclude`. - The changes made against https://github.com/ome/omeroweb-install will only be included in the documentation once they are merged and the autogen job has been run. When making changes that need to be visible in the documentation during review, you will need to: - Generate the walkthrough(s) - Open a doc PR - Copy the generated walkthrough(s) under `omero/sysadmins/unix/install-web/walkthrough `_ Model glossary """""""""""""" Content for :omero_doc:`Glossary of all OMERO Model Objects ` is generated using :omero_server_source:`GraphPathReport `. To update the content: - Run the command indicated in :omero_server_source:`GraphPathReport ` to generate :file:`EveryObject.rst` - Replace `EveryObject.rst `_ with the generated one - Open a PR with any changes Training examples """"""""""""""""" The contents of the following examples files is not automatically updated: - `omero/developers/Java.rst `_ - `omero/developers/Matlab.rst `_ - `omero/developers/Python.rst `_ When the examples under ``_ are modified, you will need to **manually** make the changes in the above files and open a doc PR.