1613313 - Network monitor is not included in the index.md file

Status: RESOLVED FIXED

(DevTools :: Documentation, defect, P3)

Description

[Jan Honza Odvarko [:Honza] (always need-info? me)]

Network monitor architecture file [2] isn't included in the index file [1] and so not available online:
https://docs.firefox-dev.tools/tools/tools.html

[1] Architecture index.md file
https://searchfox.org/mozilla-central/rev/2e355fa82aaa87e8424a9927c8136be184eeb6c7/devtools/docs/index.md#3

[2] Network monitor README.md file:
https://searchfox.org/mozilla-central/rev/2e355fa82aaa87e8424a9927c8136be184eeb6c7/devtools/client/netmonitor/README.md#1

Honza

Comment 1

[Jan Honza Odvarko [:Honza] (always need-info? me)]

Attachment: Bug 1613313 - Network monitor is not included in the index.md file

Comment 2

[Jan Honza Odvarko [:Honza] (always need-info? me)]

Sylvestre, I'd like to fix our docs and make sure that the Network monitor *.md file appears on this page:
https://firefox-source-docs.mozilla.org/devtools/index.html
How can I test this site locally?

Honza

Comment 3

[Sylvestre Ledru [:Sylvestre]]

you can see the results with
./mach doc

or you can push to try with doc generate/upload and see the results on:
http://gecko-docs.mozilla.org-l1.s3.us-west-2.amazonaws.com/index.html

don't hesitate if you need anything else

Comment 4

[Jan Honza Odvarko [:Honza] (always need-info? me)]

I am getting an error when running mach doc

# Sphinx version: 2.2.2
# Python version: 3.6.5 (CPython)
# Docutils version: 0.15.2 release
# Jinja2 version: 2.10.3
# Last messages:

# Loaded extensions:
Traceback (most recent call last):
  File "c:\src\mozilla.org\mozilla-central\obj-x86_64-pc-mingw32\_virtualenvs\moztreedocs-OSceHKx-\Lib\site-packages\sphinx\cmd\build.py", line 275, in build_main
    args.tags, args.verbosity, args.jobs, args.keep_going)
  File "c:\src\mozilla.org\mozilla-central\obj-x86_64-pc-mingw32\_virtualenvs\moztreedocs-OSceHKx-\Lib\site-packages\sphinx\application.py", line 243, in __init__
    self.setup_extension(extension)
  File "c:\src\mozilla.org\mozilla-central\obj-x86_64-pc-mingw32\_virtualenvs\moztreedocs-OSceHKx-\Lib\site-packages\sphinx\application.py", line 402, in setup_extension
    self.registry.load_extension(self, extname)
  File "c:\src\mozilla.org\mozilla-central\obj-x86_64-pc-mingw32\_virtualenvs\moztreedocs-OSceHKx-\Lib\site-packages\sphinx\registry.py", line 487, in load_extension
    metadata = setup(app)
  File "c:\src\mozilla.org\mozilla-central\python/mozbuild\mozbuild\sphinx.py", line 183, in setup
    manager.generate_docs(app)
  File "c:\src\mozilla.org\mozilla-central\tools\moztreedocs\__init__.py", line 96, in generate_docs
    self._synchronize_docs()
  File "c:\src\mozilla.org\mozilla-central\tools\moztreedocs\__init__.py", line 164, in _synchronize_docs
    self._process_markdown(m, source_path, os.path.join(".", target))
  File "c:\src\mozilla.org\mozilla-central\tools\moztreedocs\__init__.py", line 127, in _process_markdown
    post = frontmatter.load(f)
  File "c:\src\mozilla.org\mozilla-central\obj-x86_64-pc-mingw32\_virtualenvs\moztreedocs-OSceHKx-\Lib\site-packages\frontmatter\__init__.py", line 107, in load
    text = fd.read()
  File "c:\mozilla-build\python3\lib\encodings\cp1250.py", line 23, in decode
    return codecs.charmap_decode(input,self.errors,decoding_table)[0]
UnicodeDecodeError: 'charmap' codec can't decode byte 0x88 in position 189: character maps to <undefined>

Output:

Encoding error:
'charmap' codec can't decode byte 0x88 in position 189: character maps to <undefined>
./mach: failed to generate documentation:
c:\src\mozilla.org\mozilla-central: sphinx return code 2

What's wrong?

Comment 5

[Sylvestre Ledru [:Sylvestre]]

Sorry for the latency, I am on pto. I don't know much about mac doc on Windows. Sorry :(

Comment 6

[Jan Honza Odvarko [:Honza] (always need-info? me)]

The issue described in the previous comment solved in bug 1615223, thanks!
Honza

Comment 7

[Jan Honza Odvarko [:Honza] (always need-info? me)]

Attachment: imported patch net-doc.diff

Comment 8

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/81a217cfda22
Network monitor is not included in the index.md file r=jdescottes

Comment 9

[Alexandru Michis [:malexandru]]

https://hg.mozilla.org/mozilla-central/rev/81a217cfda22

Comment 10

[Jan Honza Odvarko [:Honza] (always need-info? me)]

Sylvestre, the patch didn't fix the original problem.

Here is a quick link to the doc
https://firefox-source-docs.mozilla.org/devtools/index.html#tool-architectures

The Network panel isn't in the TOC.

Note that it didn't work for me on my Win10 machine but, it worked when building the docs on Mac.

Do you know what the problem is or who could help?

Thanks!

Honza

Comment 11

[Sylvestre Ledru [:Sylvestre]]

First, sorry about the latency.
I am not very familiar with the md/rst integration.

A few options:

• add devtools/client/netmonitor/ to the index of docs
• move devtools/client/netmonitor/doc/architecture.md with the rest of the doc
• workaround the build doc process to add a symlink (ugly...)
• debug https://github.com/readthedocs/recommonmark/ to see what is happening. if there is a voodoo workaround available
  (probably other)