Bug 1606026: Move documentation entry point to docs/ r=sylvestre
authorEthan Glasser-Camp <eglassercamp@mozilla.com>
Mon, 06 Jan 2020 16:14:11 +0000
changeset 508941 f7974eae3d6404f81c645dc072909d28738e33e1
parent 508940 8d2a9c2c512d0a2ab7885fe3b878ef892cc7e67f
child 508942 d03b5479fab3073cdd0759f459e271447db4ff82
push id104320
push usereglassercamp@mozilla.com
push dateMon, 06 Jan 2020 16:39:49 +0000
treeherderautoland@d03b5479fab3 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewerssylvestre
bugs1606026
milestone73.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1606026: Move documentation entry point to docs/ r=sylvestre Differential Revision: https://phabricator.services.mozilla.com/D58552
build/sparse-profiles/sphinx-docs
docs/conf.py
docs/config.yml
docs/index.rst
docs/jsdoc.json
moz.build
tools/docs/conf.py
tools/docs/config.yml
tools/docs/docs/adding-documentation.rst
tools/docs/index.rst
tools/docs/jsdoc.json
tools/lint/codespell.yml
tools/moztreedocs/__init__.py
tools/moztreedocs/mach_commands.py
--- a/build/sparse-profiles/sphinx-docs
+++ b/build/sparse-profiles/sphinx-docs
@@ -1,12 +1,13 @@
 %include build/sparse-profiles/mach
 
 [include]
 # Code for generating docs.
+glob:docs/**
 glob:tools/docs/**
 glob:tools/moztreedocs/**
 
 # Potential docs sources
 glob:**/*.rst
 glob:**/*.md
 glob:**/*.js
 glob:**/*.jsm
rename from tools/docs/conf.py
rename to docs/conf.py
--- a/tools/docs/conf.py
+++ b/docs/conf.py
@@ -9,17 +9,17 @@ import re
 import sys
 
 from datetime import datetime
 
 from recommonmark.transform import AutoStructify
 
 # Set up Python environment to load build system packages.
 OUR_DIR = os.path.dirname(__file__)
-topsrcdir = os.path.normpath(os.path.join(OUR_DIR, '..', '..'))
+topsrcdir = os.path.normpath(os.path.join(OUR_DIR, '..'))
 
 EXTRA_PATHS = (
     'layout/tools/reftest',
     'python/mach',
     'python/mozbuild',
     'python/mozversioncontrol',
     'testing/mozbase/manifestparser',
     'testing/mozbase/mozfile',
rename from tools/docs/config.yml
rename to docs/config.yml
rename from tools/docs/index.rst
rename to docs/index.rst
rename from tools/docs/jsdoc.json
rename to docs/jsdoc.json
--- a/moz.build
+++ b/moz.build
@@ -23,16 +23,20 @@ with Files('client.*'):
     BUG_COMPONENT = ('Firefox Build System', 'General')
 
 with Files('CLOBBER'):
     BUG_COMPONENT = ('Firefox Build System', 'General')
 
 with Files('*configure*'):
     BUG_COMPONENT = ('Firefox Build System', 'General')
 
+with Files("docs/**"):
+    BUG_COMPONENT = ("Firefox Build System", "Generated Documentation")
+    SCHEDULES.exclusive = ['docs']
+
 with Files('mach'):
     BUG_COMPONENT = ('Firefox Build System', 'Mach Core')
 
 with Files('*moz*'):
     BUG_COMPONENT = ('Firefox Build System', 'General')
 
 with Files('GNUmakefile'):
     BUG_COMPONENT = ('Firefox Build System', 'General')
--- a/tools/docs/docs/adding-documentation.rst
+++ b/tools/docs/docs/adding-documentation.rst
@@ -18,13 +18,13 @@ 3. In a ``moz.build`` file (typically th
    the ``docs`` directory), define ``SPHINX_TREES`` to hook up the plumbing.
    e.g. ``SPHINX_TREES['featureX'] = 'docs'``. This says *the ``docs``
    directory under the current directory should be installed into the
    Sphinx documentation tree under ``/featureX``*.
 4. If you have Python packages you would like to generate Python API
    documentation for, you can use ``SPHINX_PYTHON_PACKAGE_DIRS`` to
    declare directories containing Python packages. e.g.
    ``SPHINX_PYTHON_PACKAGE_DIRS += ['mozpackage']``.
-5. In ``tools/docs/config.yml``, defines in which category the doc
+5. In ``docs/config.yml``, defines in which category the doc
    should go.
 6. Verify the rst syntax using `./mach lint -l rst`_
 
 .. _./mach lint -l rst: /tools/lint/linters/rstlinter.html
--- a/tools/lint/codespell.yml
+++ b/tools/lint/codespell.yml
@@ -12,16 +12,17 @@ codespell:
         - browser/extensions/report-site-issue/locales/en-US/
         - browser/installer/windows/docs/
         - browser/locales/en-US/
         - build/docs/
         - devtools/client/locales/en-US/
         - devtools/docs/
         - devtools/shared/locales/en-US/
         - devtools/startup/locales/en-US/
+        - docs/
         - dom/docs/
         - dom/locales/en-US/
         - gfx/docs/
         - intl/docs/
         - intl/locales/en-US/
         - js/src/doc/
         - layout/tools/layout-debug/ui/locale/en-US/
         - mobile/android/branding/
--- a/tools/moztreedocs/__init__.py
+++ b/tools/moztreedocs/__init__.py
@@ -17,17 +17,17 @@ from mozpack.manifests import InstallMan
 
 import frontmatter
 import sphinx
 import sphinx.ext.apidoc
 
 here = os.path.abspath(os.path.dirname(__file__))
 build = MozbuildObject.from_environment(cwd=here)
 
-MAIN_DOC_PATH = os.path.normpath(os.path.join(build.topsrcdir, 'tools', 'docs'))
+MAIN_DOC_PATH = os.path.normpath(os.path.join(build.topsrcdir, 'docs'))
 
 logger = sphinx.util.logging.getLogger(__name__)
 
 
 @memoize
 def read_build_config(docdir):
     """Read the active build config and return the relevant doc paths.
 
@@ -198,17 +198,17 @@ class _SphinxManager(object):
         # Format categories like indexes
         cats = '\n'.join(CATEGORIES.values()).split("\n")
         # Remove heading spaces
         cats = [os.path.normpath(x.strip()) for x in cats]
         indexes = tuple(set(indexes) - set(cats))
         if indexes:
             # In case a new doc isn't categorized
             print(indexes)
-            raise Exception("Uncategorized documentation. Please add it in tools/docs/config.yml")
+            raise Exception("Uncategorized documentation. Please add it in docs/config.yml")
 
         data = data.format(**CATEGORIES)
 
         with open(os.path.join(self.staging_dir, 'index.rst'), 'w') as fh:
             fh.write(data)
 
 
 manager = _SphinxManager(build.topsrcdir, MAIN_DOC_PATH)
--- a/tools/moztreedocs/mach_commands.py
+++ b/tools/moztreedocs/mach_commands.py
@@ -77,17 +77,17 @@ class Documentation(MachCommandBase):
 
         import webbrowser
         from livereload import Server
         from moztreedocs.package import create_tarball
 
         outdir = outdir or os.path.join(self.topobjdir, 'docs')
         savedir = os.path.join(outdir, fmt)
 
-        path = path or os.path.join(self.topsrcdir, 'tools')
+        path = path or self.topsrcdir
         path = os.path.normpath(os.path.abspath(path))
 
         docdir = self._find_doc_dir(path)
         if not docdir:
             print(self._dump_sphinx_backtrace())
             return die('failed to generate documentation:\n'
                        '%s: could not find docs at this location' % path)